hledger 1.33.1 → 1.34

raw patch · 60 files changed

+34203/−66721 lines, 60 filesdep +ghc-debug-stubdep ~basedep ~hledger-libPVP ok

version bump matches the API change (PVP)

Dependencies added: ghc-debug-stub

Dependency ranges changed: base, hledger-lib

API changes (from Hackage documentation)

Files

• CHANGES.md +94/−3
• Hledger/Cli.hs +61/−80
• Hledger/Cli/CliOptions.hs +172/−126
• Hledger/Cli/Commands.hs +70/−61
• Hledger/Cli/Commands/Accounts.hs +1/−1
• Hledger/Cli/Commands/Accounts.txt +1/−1
• Hledger/Cli/Commands/Activity.hs +1/−1
• Hledger/Cli/Commands/Add.txt +22/−31
• Hledger/Cli/Commands/Aregister.hs +1/−1
• Hledger/Cli/Commands/Aregister.txt +2/−2
• Hledger/Cli/Commands/Balance.hs +1/−1
• Hledger/Cli/Commands/Balance.txt +6/−1
• Hledger/Cli/Commands/Balancesheet.txt +10/−8
• Hledger/Cli/Commands/Check.hs +20/−18
• Hledger/Cli/Commands/Check.txt +64/−53
• Hledger/Cli/Commands/Close.hs +1/−1
• Hledger/Cli/Commands/Codes.hs +1/−1
• Hledger/Cli/Commands/Descriptions.hs +1/−1
• Hledger/Cli/Commands/Help.hs +7/−6
• Hledger/Cli/Commands/Help.txt +21/−21
• Hledger/Cli/Commands/Import.hs +1/−1
• Hledger/Cli/Commands/Import.txt +61/−54
• Hledger/Cli/Commands/Incomestatement.txt +10/−7
• Hledger/Cli/Commands/Notes.hs +1/−1
• Hledger/Cli/Commands/Payees.hs +1/−1
• Hledger/Cli/Commands/Prices.hs +1/−1
• Hledger/Cli/Commands/Print.hs +1/−1
• Hledger/Cli/Commands/Print.txt +1/−1
• Hledger/Cli/Commands/Register.hs +1/−1
• Hledger/Cli/Commands/Rewrite.hs +1/−1
• Hledger/Cli/Commands/Roi.hs +1/−1
• Hledger/Cli/Commands/Stats.hs +1/−1
• Hledger/Cli/Commands/Tags.hs +1/−1
• Hledger/Cli/CompoundBalanceCommand.hs +1/−1
• Hledger/Cli/DocFiles.hs +91/−63
• Hledger/Cli/Version.hs +19/−23
• embeddedfiles/hledger-accounts.md +36/−0
• embeddedfiles/hledger-add.md +24/−0
• embeddedfiles/hledger-aregister.md +20/−0
• embeddedfiles/hledger-balance.md +37/−0
• embeddedfiles/hledger-balancesheet.md +33/−0
• embeddedfiles/hledger-import.md +28/−0
• embeddedfiles/hledger-incomestatement.md +21/−0
• embeddedfiles/hledger-print.md +32/−0
• embeddedfiles/hledger-ui.1 +118/−213
• embeddedfiles/hledger-ui.info +166/−317
• embeddedfiles/hledger-ui.md +32/−0
• embeddedfiles/hledger-ui.txt +122/−217
• embeddedfiles/hledger-web.1 +147/−230
• embeddedfiles/hledger-web.info +135/−257
• embeddedfiles/hledger-web.md +32/−0
• embeddedfiles/hledger-web.txt +121/−206
• embeddedfiles/hledger.1 +11299/−11339
• embeddedfiles/hledger.info +11824/−11817
• embeddedfiles/hledger.md +37/−0
• embeddedfiles/hledger.txt +9146/−9115
• hledger.1 +0/−11463
• hledger.cabal +43/−14
• hledger.info +0/−11837
• hledger.txt +0/−9119

@@ -7,12 +7,12 @@  Breaking changes -Fixes- Features  Improvements +Fixes+ Docs  Scripts/addons@@ -23,6 +23,98 @@ User-visible changes in the hledger command line tool and library.  +# 1.34 2024-06-01++Breaking changes++- `check ordereddates` no longer supports `--date2`.+  Also (not a breaking change): `--date2` and secondary dates are now officially+  [deprecated](https://hledger.org/1.34/hledger.html#secondary-dates) in hledger,+  though kept for compatibility.++Features++- You can now get a quick list of example command lines for hledger or+  its most useful subcommands by adding the `--tldr` flag (or just+  `--tl`).  For best appearance you should install the [`tldr`][tldr] client,+  though it's not required.++  These short "tldr pages" are a great counterbalance to verbose PTA docs.+  You can also use `tldr` without hledger to view the latest versions, or translations:\+  `tldr hledger[-COMMAND]`.+  Or you can [browse tldr pages online](https://tldr.inbrowser.app/search?query=hledger+).+  Consider contributing translations!+  More tips at <https://github.com/simonmichael/hledger/tree/master/doc/tldr>.++[tldr]: https://tldr.sh++Improvements++- The `hledger` commands list has been reorganised,+  with commands listed roughly in the order you'll need them.++- The general flags descriptions in `--help` have been updated and grouped.++- Correctness checks now run in a documented order.  `commodities` are+  now checked before `accounts`, and `tags` before `recentassertions`.+  When both `ordereddates` and `assertions` checks are enabled,+  `ordereddates` now runs first, giving more useful error messages.++- `-I`/`--ignore-assertions` is now overridden by `-s`/`--strict`+  (or `check assertions`), enabling more flexible workflows.+  Eg you can `alias hl="hledger -I"` to delay balance assertions+  checking until you add `-s` to commands.++- `--color` and `--pretty` now also accept `y` or `n` as argument.++- When built with the `ghcdebug` flag and started with `--debug=-1`,+  hledger can be controlled by [ghc-debug] clients like+  ghc-debug-brick or a ghc-debug query script, for analysing+  memory/profile info.++[ghc-debug]: https://gitlab.haskell.org/ghc/ghc-debug++Fixes++- `hledger COMMAND --man` and `hledger help TOPIC --man` now properly scroll+  the man page to the TOPIC or COMMAND heading.+  The exact/prefix matching behaviour has been clarified in `help --help`.++- In journal files, `include` directives with trailing whitespace are now parsed correctly.++- The help command's help flags are now consistent with other commands+  (and it has `--debug` as a hidden flag).++- Build errors with GHC 8.10 have been fixed. [#2198]++Docs++- The tables of contents on hledger.org pages now just list top-level headings,+  (and the hledger manual structure has been adjusted for this).+  This makes the hledger manual on hledger.org more scannable and less scary.+- add: drop lengthy transcript, add simpler example commands (from tldr)+- Amount formatting: move down, it's not the best first topic+- balance: mention the `--summary-only` flag+- check: expand check descriptions+- examples: CSV rules: vanguard, fidelity, paypal updates+- Generating data: rewrite+- JSON output: link to OpenAPI spec+- manuals: synopsis, options cleanup/consistency+- Options: correction, NO_COLOR does not override --color+- PART 4: COMMANDS: reorganise into groups, like the CLI commands list.+- Period expressions: mention last day of month adjusting [#2005]+- Secondary dates: expand, and declare them deprecated.+- Time periods cleanup, simplify markup+- Unicode characters: mention UTF-8 on windows++Scripts/addons++- Added `hledger-pricehist`, an alias for the `pricehist` market price+  fetcher so that it can appear in hledger's commands list.++[#2005]: https://github.com/simonmichael/hledger/issues/2005+[#2198]: https://github.com/simonmichael/hledger/issues/2198+ # 1.33.1 2024-05-02  - process >=1.6.19.0 seems not strictly needed and is no longer required,@@ -48,7 +140,6 @@   # 1.33 2024-04-18-   Breaking changes

@@ -1,8 +1,3 @@-{-# LANGUAGE LambdaCase #-}-{-# LANGUAGE TemplateHaskell #-}-{-# OPTIONS_GHC -Wno-unrecognised-pragmas #-}-{-# HLINT ignore "Unused LANGUAGE pragma" #-}- {-|  This is the root module of the @hledger@ package,@@ -69,9 +64,12 @@  -} +{-# LANGUAGE LambdaCase #-}++{-# OPTIONS_GHC -Wno-unrecognised-pragmas #-}+{-# HLINT ignore "Unused LANGUAGE pragma" #-}+ module Hledger.Cli (-  prognameandversion,-  versionString,   main,   mainmode,   argsToCliOpts,@@ -90,7 +88,9 @@ import Control.Monad (when) import Data.List import qualified Data.List.NonEmpty as NE+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.Environment import System.Exit@@ -98,12 +98,6 @@ import System.Process import Text.Printf -import Data.Time.Clock.POSIX (getPOSIXTime)---import GitHash (tGitInfoCwdTry)-import System.Console.CmdArgs.Explicit hiding (Name) -- don't clash with hledger-ui- import Hledger import Hledger.Cli.CliOptions import Hledger.Cli.Commands@@ -112,29 +106,11 @@ import Hledger.Cli.Version  --- | The program name and version string for this build of the hledger tool,--- including any git info available at build time.-prognameandversion :: String-prognameandversion = versionString progname packageversion---- | A helper to generate the best version string we can from the given --- program name and package version strings, current os and architecture,--- and any git info available at build time (commit hash, commit date, branch--- name, patchlevel since latest release tag for that program's package).--- Typically called for programs "hledger", "hledger-ui", or "hledger-web".------ The git info changes whenever any file in the repository changes. --- Keeping this template haskell call here and not down in Hledger.Cli.Version--- helps reduce the number of modules recompiled.-versionString :: ProgramName -> PackageVersion -> String-versionString = versionStringWith $$tGitInfoCwdTry-- -- | The overall cmdargs mode describing hledger's command-line options and subcommands. mainmode addons = defMode {-  modeNames = [progname ++ " [CMD]"]+  modeNames = [progname ++ " [COMMAND]"]  ,modeArgs = ([], Just $ argsFlag "[ARGS]")- ,modeHelp = unlines ["hledger's main command line interface. Runs builtin commands and other hledger executables. Type \"hledger\" to list available commands."]+ ,modeHelp = unlines ["hledger's main command line interface. Run with no ARGS to list commands."]  ,modeGroupModes = Group {     -- subcommands in the unnamed group, shown first:     groupUnnamed = [@@ -146,12 +122,8 @@    ,groupHidden = map fst builtinCommands ++ map addonCommandMode addons    }  ,modeGroupFlags = Group {-     -- flags in named groups:-     groupNamed = [-        (  "General input flags",     inputflags)-       ,("\nGeneral reporting flags", reportflags)-       ,("\nGeneral help flags",      helpflags)-       ]+     -- 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:@@ -159,21 +131,25 @@         [detailedversionflag]         -- ++ inputflags -- included here so they'll not raise a confusing error if present with no COMMAND     }- ,modeHelpSuffix = "Examples:" :-    map (progname ++) [-     "                         list commands"-    ," CMD [--] [OPTS] [ARGS]  run a command (use -- with addon commands)"-    ,"-CMD [OPTS] [ARGS]       or run addon commands directly"-    ," -h                      show general usage"-    ," CMD -h                  show command usage"-    ," help [MANUAL]           show any of the hledger manuals in various formats"-    ]+ ,modeHelpSuffix = []+    -- "Examples:" :+    -- map (progname ++) [+    --  "                         list commands"+    -- ," CMD [--] [OPTS] [ARGS]  run a command (use -- with addon commands)"+    -- ,"-CMD [OPTS] [ARGS]       or run addon commands directly"+    -- ," -h                      show general usage"+    -- ," CMD -h                  show command usage"+    -- ," help [MANUAL]           show any of the hledger manuals in various formats"+    -- ]  }  -- | Let's go! main :: IO ()-main = do+main = withGhcDebug' $ do+  when (ghcDebugMode == GDPauseAtStart) $ ghcDebugPause'+   starttime <- getPOSIXTime+   -- try to encourage user's $PAGER to properly display ANSI   when useColorOnStdout setupPager @@ -212,23 +188,25 @@   opts' <- argsToCliOpts args addons   let opts = opts'{progstarttime_=starttime} -  -- select an action and run it.+  -- select an action and prepare to run it   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-    hasVersion           = ("--version" `elem`)-    printUsage           = pager $ showModeUsage $ mainmode addons-    badCommandError      = error' ("command "++rawcmd++" is not recognized, run with no command to see a list") >> exitFailure  -- PARTIAL:-    hasHelpFlag args1     = any (`elem` args1) ["-h","--help"]-    hasManFlag args1      = (`elem` args1) "--man"-    hasInfoFlag args1     = (`elem` args1) "--info"+    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-      | hasHelpFlag args = pager $ showModeUsage mode1-      | hasInfoFlag args = runInfoForTopic "hledger" (headMay $ modeNames mode1)-      | hasManFlag args  = runManForTopic "hledger" (headMay $ modeNames mode1)-      | otherwise        = f+      | 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@@ -241,29 +219,26 @@   dbgIO "interval from opts" (interval_ . _rsReportOpts $ reportspec_ opts)   dbgIO "query from opts & args" (_rsQuery $ reportspec_ opts)   let-    journallesserror = error $ cmd++" tried to read the journal but is not supposed to"     runHledgerCommand-      -- high priority flags and situations. -h, then --help, then --info are highest priority.-      | isNullCommand && hasHelpFlag args = dbgIO "" "-h/--help with no command, showing general help" >> printUsage-      | isNullCommand && hasInfoFlag args = dbgIO "" "--info with no command, showing general info manual" >> runInfoForTopic "hledger" Nothing-      | isNullCommand && hasManFlag args  = dbgIO "" "--man with no command, showing general man page" >> runManForTopic "hledger" Nothing-      | not (isExternalCommand || hasHelpFlag args || hasInfoFlag args || hasManFlag args)-        && (hasVersion args) --  || (hasVersion argsaftercmd && isInternalCommand))-                                 = putStrLn prognameandversion-      -- \| (null externalcmd) && boolopt "binary-filename" rawopts = putStrLn $ binaryfilename progname-      -- \| "--browse-args" `elem` args     = System.Console.CmdArgs.Helper.execute "cmdargs-browser" mainmode' args >>= (putStr . show)-      | isNullCommand            = dbgIO "" "no command, showing commands list" >> printCommandsList prognameandversion addons-      | isBadCommand             = badCommandError+      -- 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        -- 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 journallesserror+          _ | 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)+              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)         )@@ -284,8 +259,11 @@       -- shouldn't reach here       | otherwise                = usageError ("could not understand the arguments "++show args) >> exitFailure +  -- do it   runHledgerCommand +  when (ghcDebugMode == GDPauseAtEnd) $ ghcDebugPause'+ -- | Parse hledger CLI options from these command line arguments and -- add-on command names, or raise any error. argsToCliOpts :: [String] -> [String] -> IO CliOpts@@ -340,7 +318,10 @@ isValue _       = True  flagstomove = inputflags ++ reportflags ++ helpflags-noargflagstomove  = concatMap flagNames $ filter ((==FlagNone).flagInfo) flagstomove+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

@@ -15,20 +15,29 @@ {-# LANGUAGE TypeOperators       #-}  module Hledger.Cli.CliOptions (+  progname,+  prognameandversion,    -- * cmdargs flags & modes+  inputflags,+  reportflags,   helpflags,+  helpflagstitle,   detailedversionflag,   flattreeflags,   hiddenflags,-  inputflags,-  reportflags,   -- outputflags,   outputFormatFlag,   outputFileFlag,   generalflagsgroup1,   generalflagsgroup2,   generalflagsgroup3,+  mkgeneralflagsgroups1,+  mkgeneralflagsgroups2,+  mkgeneralflagsgroups3,+  cligeneralflagsgroups1,+  cligeneralflagsgroups2,+  cligeneralflagsgroups3,   defMode,   defCommandMode,   addonCommandMode,@@ -80,13 +89,14 @@ import Data.Default import Data.Either (fromRight, isRight) import Data.List.Extra (groupSortOn, intercalate, isInfixOf, nubSort)-import qualified Data.List.NonEmpty as NE (NonEmpty, fromList, head, nonEmpty, singleton)+import qualified Data.List.NonEmpty as NE (NonEmpty, fromList, head, nonEmpty) import Data.List.Split (splitOn) import Data.Maybe --import Data.String.Here -- import Data.Text (Text) import qualified Data.Text as T import Data.Void (Void)+import GitHash (tGitInfoCwdTry) import Safe import String.ANSI import System.Console.CmdArgs hiding (Default,def)@@ -110,89 +120,47 @@ import Data.List (isPrefixOf, isSuffixOf)  --- common cmdargs flags--- keep synced with flag docs in doc/common.m4+-- | The name of this program's executable.+progname :: ProgramName+progname = "hledger" --- | Common help flags: --help, --debug, --version...-helpflags :: [Flag RawOpts]-helpflags = [-  -- XXX why are these duplicated in defCommandMode below ?-  flagNone ["help","h"] (setboolopt "help") "show general help (or after CMD, command help)"- ,flagNone ["man"] (setboolopt "man") "show user manual with man"- ,flagNone ["info"] (setboolopt "info") "show info manual with info"- -- ,flagNone ["browse-args"] (setboolopt "browse-args") "use a web UI to select options and build up a command line"- ,flagReq  ["debug"] (\s opts -> Right $ setopt "debug" s opts) "[N]" "show debug output (levels 1-9, default: 1)"- ,flagNone ["version"] (setboolopt "version") "show version information"- ]+-- | Generate the version string for this program.+-- The template haskell call is here rather than in Hledger.Cli.Version to avoid wasteful recompilation.+prognameandversion :: String+prognameandversion =+  versionStringWith+  $$tGitInfoCwdTry+#ifdef GHCDEBUG+  True+#else+  False+#endif+  progname+  packageversion --- | A hidden flag just for the hledger executable.-detailedversionflag :: Flag RawOpts-detailedversionflag = flagNone ["version+"] (setboolopt "version+") "show version information with extra detail"+-- common cmdargs flags+-- keep synced with flag docs in doc/common.m4  -- | Common input-related flags: --file, --rules-file, --alias... inputflags :: [Flag RawOpts] inputflags = [-  flagReq  ["file","f"]      (\s opts -> Right $ setopt "file" s opts) "FILE" "use a different input file. For stdin, use - (default: $LEDGER_FILE or $HOME/.hledger.journal)"- ,flagReq  ["rules-file"]    (\s opts -> Right $ setopt "rules-file" s opts) "RFILE" "CSV conversion rules file (default: FILE.rules)"- ,flagReq  ["alias"]         (\s opts -> Right $ setopt "alias" s opts)  "OLD=NEW" "rename accounts named OLD to NEW"- ,flagReq  ["pivot"]         (\s opts -> Right $ setopt "pivot" s opts)  "TAGNAME" "use some other field/tag for account names"- ,flagNone ["ignore-assertions","I"] (setboolopt "ignore-assertions") "ignore any balance assertions"- ,flagNone ["strict","s"]    (setboolopt "strict") "do extra error checking (check that all posted accounts are declared)"- ]---- | Common report-related flags: --period, --cost, etc.-reportflags :: [Flag RawOpts]-reportflags = [--  -- report period & interval-  flagReq  ["begin","b"]     (\s opts -> Right $ setopt "begin" s opts) "DATE" "include postings/txns on or after this date (will be adjusted to preceding subperiod start when using a report interval)"- ,flagReq  ["end","e"]       (\s opts -> Right $ setopt "end" s opts) "DATE" "include postings/txns before this date (will be adjusted to following subperiod end when using a report interval)"- ,flagNone ["daily","D"]     (setboolopt "daily") "multiperiod/multicolumn report by day"- ,flagNone ["weekly","W"]    (setboolopt "weekly") "multiperiod/multicolumn report by week"- ,flagNone ["monthly","M"]   (setboolopt "monthly") "multiperiod/multicolumn report by month"- ,flagNone ["quarterly","Q"] (setboolopt "quarterly") "multiperiod/multicolumn report by quarter"- ,flagNone ["yearly","Y"]    (setboolopt "yearly") "multiperiod/multicolumn report by year"- ,flagReq  ["period","p"]    (\s opts -> Right $ setopt "period" s opts) "PERIODEXP" "set start date, end date, and/or report interval all at once"- ,flagNone ["date2"]         (setboolopt "date2") "match the secondary date instead. See command help for other effects. (--effective, --aux-date also accepted)"  -- see also hiddenflags- ,flagReq  ["today"]         (\s opts -> Right $ setopt "today" s opts) "DATE" "override today's date (affects relative smart dates, for tests/examples)"- -  -- status/realness/depth/zero filters- ,flagNone ["unmarked","U"]  (setboolopt "unmarked") "include only unmarked postings/txns (can combine with -P or -C)"- ,flagNone ["pending","P"]   (setboolopt "pending") "include only pending postings/txns"- ,flagNone ["cleared","C"]   (setboolopt "cleared") "include only cleared postings/txns"- ,flagNone ["real","R"]      (setboolopt "real") "include only non-virtual postings"- ,flagReq  ["depth"]         (\s opts -> Right $ setopt "depth" s opts) "NUM" "(or -NUM): hide accounts/postings deeper than this"- ,flagNone ["empty","E"]     (setboolopt "empty") "show items with zero amount, normally hidden (and vice-versa in hledger-ui/hledger-web)"+   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." -  -- valuation, including https://hledger.org/dev/hledger.html#valuation-type :- ,flagNone ["B","cost"]      (setboolopt "B")-   "show amounts converted to their cost/selling amount, using the transaction price."- ,flagNone ["V","market"]    (setboolopt "V")-   (unwords-     ["show amounts converted to period-end market value in their default valuation commodity."-     ,"Equivalent to --value=end."-     ])- ,flagReq ["X","exchange"]   (\s opts -> Right $ setopt "X" s opts) "COMM"-   (unwords-     ["show amounts converted to current (single period reports)"-     ,"or period-end (multiperiod reports) market value in the specified commodity."-     ,"Equivalent to --value=end,COMM."-     ])- ,flagReq  ["value"]         (\s opts -> Right $ setopt "value" s opts) "TYPE[,COMM]"-   (unlines-     ["show amounts converted with valuation TYPE, and optionally to specified commodity COMM. TYPE can be:"-     ,"'then': convert to contemporaneous market value, in default valuation commodity or COMM (print & register commands only)"-     ,"'end':  convert to period-end market value, in default valuation commodity or COMM"-     ,"'now':  convert to current market value, in default valuation commodity or COMM"-     ,"YYYY-MM-DD: convert to market value on the given date, in default valuation commodity or COMM"-     ])-  ,flagNone ["infer-equity"] (setboolopt "infer-equity")-    "infer conversion equity postings from costs"-  ,flagNone ["infer-costs"] (setboolopt "infer-costs")-    "infer costs from conversion equity postings"+  ,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"+  ,flagOpt "" ["forecast"]    (\s opts -> Right $ setopt "forecast" s opts) "PERIOD" (unwords+    [ "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."+    ])+  ,flagNone ["ignore-assertions","I"] (setboolopt "ignore-assertions") "don't check balance assertions by default"+  ,flagNone ["infer-costs"] (setboolopt "infer-costs") "infer conversion equity postings from costs"+  ,flagNone ["infer-equity"] (setboolopt "infer-equity") "infer costs from conversion equity postings"   -- history of this flag so far, lest we be confused:   --  originally --infer-value-  --  2021-02 --infer-market-price added, --infer-value deprecated +  --  2021-02 --infer-market-price added, --infer-value deprecated   --  2021-09   --   --infer-value hidden   --   --infer-market-price renamed to --infer-market-prices, old spelling still works@@ -200,41 +168,91 @@   --   some related prices command changes   --    --costs deprecated and hidden, uses --infer-market-prices instead   --    --inverted-costs renamed to --infer-reverse-prices- ,flagNone ["infer-market-prices"] (setboolopt "infer-market-prices") -    "use costs as additional market prices, as if they were P directives"+  ,flagNone ["infer-market-prices"] (setboolopt "infer-market-prices") "infer market prices from costs"+  ,flagReq  ["pivot"]         (\s opts -> Right $ setopt "pivot" s opts)  "TAGNAME" "use a different field or tag as account names"+  ,flagNone ["strict","s"]    (setboolopt "strict") "do extra error checks (and override -I)"    -- generating transactions/postings- ,flagOpt "" ["forecast"]    (\s opts -> Right $ setopt "forecast" s opts) "PERIOD" (unwords-   [ "Generate transactions from periodic rules,"-   , "between the latest recorded txn and 6 months from today,"-   , "or during the specified PERIOD (= is required)."-   , "Auto posting rules will be applied to these transactions as well."-   , "Also, in hledger-ui make future-dated transactions visible."-   ])- ,flagNone ["auto"]          (setboolopt "auto") "Generate extra postings by applying auto posting rules to all txns (not just forecast txns)."- ,flagNone ["verbose-tags"]  (setboolopt "verbose-tags") "Add visible tags indicating transactions or postings which have been generated/modified."+  ,flagNone ["verbose-tags"]  (setboolopt "verbose-tags") "add tags indicating generated/modified data"+  ] +-- | Common report-related flags: --period, --cost, etc.+reportflags :: [Flag RawOpts]+reportflags = [++  -- report period & interval+  flagReq  ["begin","b"]     (\s opts -> Right $ setopt "begin" s opts) "DATE" "include postings/transactions on/after this date"+ ,flagReq  ["end","e"]       (\s opts -> Right $ setopt "end" s opts) "DATE" "include postings/transactions before this date (with a report interval, will be adjusted to following subperiod end)"+ ,flagNone ["daily","D"]     (setboolopt "daily")     "multiperiod report with 1 day interval"+ ,flagNone ["weekly","W"]    (setboolopt "weekly")    "multiperiod report with 1 week interval"+ ,flagNone ["monthly","M"]   (setboolopt "monthly")   "multiperiod report with 1 month interval"+ ,flagNone ["quarterly","Q"] (setboolopt "quarterly") "multiperiod report with 1 quarter interval"+ ,flagNone ["yearly","Y"]    (setboolopt "yearly")    "multiperiod report with 1 year interval"+ ,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"+ ,flagNone ["cleared","C"]   (setboolopt "cleared")  "include only cleared postings/transactions\n(-U/-P/-C can be combined)"+ ,flagNone ["real","R"]      (setboolopt "real")     "include only non-virtual postings"+ ,flagReq  ["depth"]         (\s opts -> Right $ setopt "depth" s opts) "NUM" "or -NUM: show only top NUM levels of accounts"+ ,flagNone ["empty","E"]     (setboolopt "empty") "Show zero items, which are normally hidden.\nIn hledger-ui & hledger-web, do the opposite."++  -- valuation+ ,flagNone ["B","cost"]      (setboolopt "B") "show amounts converted to their cost/sale amount"+ ,flagNone ["V","market"]    (setboolopt "V")+    (unlines+      ["Show amounts converted to their value at period end(s) in their default valuation commodity."+      ,"Equivalent to --value=end."+      ])+ ,flagReq ["X","exchange"]   (\s opts -> Right $ setopt "X" s opts) "COMM"+    (unlines+      ["Show amounts converted to their value at period end(s) in the specified commodity."+      ,"Equivalent to --value=end,COMM."+      ])+ ,flagReq  ["value"]         (\s opts -> Right $ setopt "value" s opts) "WHEN[,COMM]"+    (unlines+      ["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"+      ])+   -- general output-related- ,flagReq ["commodity-style", "c"] (\s opts -> Right $ setopt "commodity-style" s opts) "COMM"-    "Override the commodity style in the output for the specified commodity. For example 'EUR1.000,00'."-  + ,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'"     -- This has special support in hledger-lib:colorOption, keep synced- ,flagReq  ["color","colour"] (\s opts -> Right $ setopt "color" s opts) "WHEN"+ ,flagReq  ["color","colour"] (\s opts -> Right $ setopt "color" s opts) "YN"    (unlines-     ["Should color-supporting commands use ANSI color codes in text output."-     ,"'auto' (default): whenever stdout seems to be a color-supporting terminal."-     ,"'always' or 'yes': always, useful eg when piping output into 'less -R'."-     ,"'never' or 'no': never."-     ,"A NO_COLOR environment variable overrides this."-     ])- ,flagOpt "yes" ["pretty"] (\s opts -> Right $ setopt "pretty" s opts) "WHEN"-   (unwords-     ["Show prettier output, e.g. using unicode box-drawing characters."-     ,"Accepts 'yes' (the default) or 'no'."-     ,"If you provide an argument you must use '=', e.g. '--pretty=yes'."+     ["Use ANSI color codes in text output? Can be"+     ,"'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'."      ])+ ,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]+helpflags = [+  flagNone ["help","h"] (setboolopt "help")    "show command line help"+ ,flagNone ["tldr"]     (setboolopt "tldr")    "show command examples with tldr"+ ,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"+ ]+-- 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]@@ -250,11 +268,11 @@ -- such as --effective, --aux-date. hiddenflags :: [Flag RawOpts] hiddenflags = [-   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+   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   ]  -- | Common output-related flags: --output-file, --output-format...@@ -278,11 +296,38 @@ generalflagstitle :: String generalflagstitle = "\nGeneral flags" +-- Several subsets of the standard general flags, as a single list. Old API used by some addons. generalflagsgroup1, generalflagsgroup2, generalflagsgroup3 :: (String, [Flag RawOpts]) generalflagsgroup1 = (generalflagstitle, inputflags ++ reportflags ++ helpflags) generalflagsgroup2 = (generalflagstitle, inputflags ++ helpflags) generalflagsgroup3 = (generalflagstitle, helpflags) +-- Helpers to make several subsets of the standard general flags, in separate groups. The help flags are parameterised. 2024.+mkgeneralflagsgroups1, mkgeneralflagsgroups2, mkgeneralflagsgroups3 :: [Flag RawOpts] -> [(String, [Flag RawOpts])]+mkgeneralflagsgroups1 helpflags' = [+   (inputflagstitle,  inputflags)+  ,(outputflagstitle, reportflags)+  ,(helpflagstitle,   helpflags')+  ]+mkgeneralflagsgroups2 helpflags' = [+   (inputflagstitle, inputflags)+  ,(helpflagstitle, helpflags')+  ]+mkgeneralflagsgroups3 helpflags' = [+   (helpflagstitle, helpflags')+  ]++inputflagstitle  = "\nGeneral input/data transformation flags"+outputflagstitle = "\nGeneral output/reporting flags (supported by some commands)"+helpflagstitle   = "\nGeneral help flags"++-- Several subsets of the standard general flags plus CLI help flags, as separate groups.+cligeneralflagsgroups1, cligeneralflagsgroups2, cligeneralflagsgroups3 :: [(String, [Flag RawOpts])]+cligeneralflagsgroups1 = mkgeneralflagsgroups1 helpflags+cligeneralflagsgroups2 = mkgeneralflagsgroups2 helpflags+cligeneralflagsgroups3 = mkgeneralflagsgroups3 helpflags++ -- cmdargs mode constructors  -- | An empty cmdargs mode to use as a template.@@ -316,10 +361,9 @@   ,modeGroupFlags  = Group {      groupNamed   = []     ,groupUnnamed = [-        flagNone ["help"] (setboolopt "help") "Show command-line help"-      -- ,flagNone ["help"] (setboolopt "help") "Show long help."-       ,flagNone ["man"] (setboolopt "man") "Show user manual with man"-       ,flagNone ["info"] (setboolopt "info") "Show info manual with info"+        flagNone ["help"] (setboolopt "help") "show command-line help"+       ,flagNone ["man"]  (setboolopt "man")  "show this program's user manual with man"+       ,flagNone ["info"] (setboolopt "info") "show this program's user manual with info"       ]     ,groupHidden  = []             --  flags not displayed in the usage     }@@ -348,7 +392,7 @@   ,modeGroupFlags = Group {       groupUnnamed = []      ,groupHidden  = hiddenflags-     ,groupNamed   = [generalflagsgroup1]+     ,groupNamed   = cligeneralflagsgroups1      }   } @@ -421,18 +465,20 @@   | not useColorOnStdout = id   | otherwise = unlines . zipWith (curry f) [1..] . lines   where-    f (n,s)-      | n==1 = bold s-      | s `elem` [-           "General input flags:"-          ,"General reporting flags:"-          ,"General help flags:"-          ,"Flags:"-          ,"General flags:"-          ,"Examples:"-          ] = bold s-      | otherwise = s-+    f (n,l)+      | n==1 = bold l+      | isHelpHeading l = bold l+      | otherwise = l+    -- keep synced with Hledger.Cli.mainmode:+    isHelpHeading l = isAlphaNum (headDef ' ' l) && (lastDef ' ' l == ':')+      -- any s (`isPrefixOf` s) [+      --    "General input flags"+      --   ,"General reporting flags"+      --   ,"General help flags"+      --   ,"Flags"+      --   ,"General flags"+      --   ,"Examples"+      --   ] -- | Get the most appropriate documentation topic for a mode. -- Currently, that is either the hledger, hledger-ui or hledger-web -- manual.@@ -618,7 +664,7 @@   f <- defaultJournalPath   d <- getCurrentDirectory   maybe-    (return $ NE.singleton f)+    (return $ NE.fromList [f])     (mapM (expandPathPreservingPrefix d))     $ NE.nonEmpty $ file_ opts 

@@ -65,7 +65,6 @@  import Hledger import Hledger.Cli.CliOptions-import Hledger.Cli.Version import Hledger.Cli.Commands.Accounts import Hledger.Cli.Commands.Activity import Hledger.Cli.Commands.Add@@ -195,100 +194,110 @@   --  commands.m4   --  hledger.m4.md -> Commands   --  commandsFromCommandsList. Only commands should begin with space or plus.+  -- IN PARTICULAR KEEP SYNCED WITH commandsListExtractCommands, +  -- it needs checking/updating after any wording/layout changes here    "-------------------------------------------------------------------------------"   ,progversion-  ,"Usage: hledger CMD [OPTS] [-- ADDONCMDOPTS]"+  ,"Usage: hledger COMMAND [OPTIONS] [-- ADDONOPTIONS]"   ,"Commands (builtins + addons):"   ,""-  ,bold' "ENTERING DATA (add or edit transactions, updating the journal file)"-  ," add                      add transactions using terminal prompts"-  ,"+edit                     edit a subset of transactions"-  ,"+iadd                     add transactions using a TUI"-  ," import                   add new transactions from other files, eg CSV files"-  ,""     -----------------------------------------80--------------------------------------  ,bold' "GENERATING DATA (generate entries to be added to the journal file)"-  ,"+autosync                 download/deduplicate/convert OFX data"-  ," close                    generate balance-zeroing/restoring transactions"-  ,"+interest                 generate interest transactions"-  ,"+lots sell                generate a lot-selling transaction"-  ," rewrite                  generate auto postings, like print --auto"-  ,"+stockquotes              download market prices from AlphaVantage"-  ,""-    -----------------------------------------80--------------------------------------  ,bold' "MANAGING DATA (error checking, version control..)"-  ," check                    check for various kinds of error in the data"-  ,"+check-fancyassertions    check more powerful balance assertions"-  ,"+check-tagfiles           check file paths in tag values exist"-  ," diff                     compare account transactions in two journal files"-  ,"+git                      simple version management with git"-  ,"+pijul                    simple version management with pijul"+  ,bold' "HELP (docs, demos..)"+  ," (no arguments)           show this commands list"+  ," -h [COMMAND]             show command line help"+  ," --tldr [COMMAND]         show command examples with tldr"+  ," --info [COMMAND]         show the hledger manual with info"+  ," --man  [COMMAND]         show the hledger manual with man"+  ," help [-i|-m|-p] [TOPIC]  show any topic in the hledger manual"+  ," demo [DEMO]              show brief demos in the terminal"+  ,"                          more help: https://hledger.org"   ,""     -----------------------------------------80--------------------------------------  ,bold' "FINANCIAL REPORTS (standard financial statements)"-  ," aregister (areg)         show transactions in a particular account"-  ," balancesheet (bs)        show assets, liabilities and net worth"-  ," balancesheetequity (bse) show assets, liabilities and equity"-  ," cashflow (cf)            show changes in liquid assets"-  ," incomestatement (is)     show revenues and expenses"+  ,bold' "USER INTERFACES (alternate UIs)"+  ,"+ui                       run terminal UI"                                       -- hledger-ui+  ,"+web                      run web UI"                                            -- hledger-web+                                                                                     -- see also: MoLe, https://hledger.org/mobile.html   ,""     -----------------------------------------80--------------------------------------  ,bold' "VERSATILE REPORTS (more complex/versatile reporting commands)"-  ," activity                 show a simple bar chart of posting counts per period"-  ," balance (bal)            show balance changes, end balances, budgets, gains.."-  ,"+bar                      show a balance report as a simple bar chart"-  ,"+lots                     show a commodity's lots"-  ,"+plot                     create charts from balance reports, in terminal or GUI"-  ," print                    show transactions or export journal data"-  ," register (reg)           show postings in one or more accounts & running total"-  ," roi                      show return on investments"+  ,bold' "ENTERING DATA (add or edit transactions)"+  ," add                      add transactions using interactive prompts"+  ,"+iadd                     add transactions using a TUI"                          -- hledger-iadd+  ," import                   add new transactions from other files, eg CSV files"+  ,"+edit                     edit existing transactions with $EDITOR"               -- hledger-utils   ,""     -----------------------------------------80--------------------------------------  ,bold' "BASIC REPORTS (lists and stats)"+  ,bold' "BASIC REPORTS (simple lists)"   ," accounts                 show account names"   ," codes                    show transaction codes"   ," commodities              show commodity/currency symbols"-  ," descriptions             show full transaction descriptions (payee and note)"+  ," descriptions             show transaction descriptions"   ," files                    show data files in use"   ," notes                    show note part of transaction descriptions"-  ," payees                   show payee names"+  ," payees                   show payee part of transaction descriptions"   ," prices                   show historical market prices"   ," stats                    show journal statistics"   ," tags                     show tag names"   ,""     -----------------------------------------80--------------------------------------  ,bold' "UIS (other user interfaces)"-  ,"+ui                       run terminal UI"-  ,"+web                      run web UI"+  ,bold' "STANDARD REPORTS (the most useful financial reports)"+  ," print                    show full transaction entries, or export journal data"+  ," aregister (areg)         show transactions & running balance in one account"+  ," register (reg)           show postings & running total in one or more accounts"+  ," balancesheet (bs)        show assets and liabilities"+  ," balancesheetequity (bse) show assets, liabilities and equity"+  ," cashflow (cf)            show changes in liquid assets"+  ," incomestatement (is)     show revenues and expenses"   ,""     -----------------------------------------80--------------------------------------  ,bold' "HELP (show help and docs)"-  ," hledger                          show this commands list"-  ," hledger -h                       show hledger's command-line help"-  ," hledger CMD -h                   show CMD's command-line help and manual"-  ," hledger help [-i|-m|-p] [TOPIC]  show hledger's manual with info, man, or pager"-  ," hledger demo [DEMO] [-- ASCOPTS] show brief demos on various topics"-  ," hledger test      [-- TASTYOPTS] run self tests"-  ," https://hledger.org              html manuals, tutorials, support.."+  ,bold' "ADVANCED REPORTS (more versatile/advanced reports)"+  ," balance (bal)            show balance changes, end balances, gains, budgets.."+  ,"+lots                     show a commodity's lots"                               -- hledger-lots+  ," roi                      show return on investments"   ,""     -----------------------------------------80--------------------------------------  ,bold' "OTHER (more hledger-* addon commands found in PATH)"+  ,bold' "CHARTS (bar charts, line graphs..)"+  ," activity                 show posting counts as a bar chart"+  ,"+bar                      show balances or changes as a bar chart"               -- hledger-bar+  ,"+plot                     show advanced matplotlib charts as gui/svg/png/pdf.."  -- hledger-utils+  ,""+    -----------------------------------------80-------------------------------------+  ,bold' "GENERATING DATA (generate or download journal entries; less common)"+  ,"+autosync                 download/deduplicate/show OFX data as transactions"    -- ledger-autosync+  ," close                    generate transactions to zero/restore/assert balances"+  ,"+interest                 generate transactions transferring accrued interest"   -- hledger-interest+  ,"+lots sell                generate a lot-selling transaction"                    -- hledger-lots+  ,"+pricehist                download historical market prices"                     -- pricehist+  ," rewrite                  add postings to transactions, like print --auto"+  ,""+    -----------------------------------------80-------------------------------------+  ,bold' "MAINTENANCE (error checking, data management..)"+  ," check                    run any of hledger's built-in correctness checks"+  ,"+check-fancyassertions    check more powerful balance assertions"                -- hledger-check-fancyassertions+  ,"+check-tagfiles           check that files referenced in tag values exist"       -- hledger-check-tagfiles+  ," diff                     compare an account's transactions in two journals"+  ,"+git                      save or view journal file history simply in git"       -- hledger-git+  ,"+pijul                    save or view journal file history simply in pijul"     -- hledger-pijul+  ," test                     run some self tests"+  ,""+    -----------------------------------------80-------------------------------------+  ,bold' "OTHER ADDONS (more hledger-* commands found in PATH):"   ]   ++ map (' ':) (lines $ multicol 79 othercmds)   ++ [""]  -- | Extract just the command names from the default commands list above,--- (the first word of lines between "Usage:" and "HELP" beginning with a space or plus sign),+-- (the first word of lines between "Usage:" and "OTHER" beginning with a space or plus sign), -- in the order they occur. With a true first argument, extracts only the addon command names.--- Needs to be kept synced with commandsList. commandsListExtractCommands :: Bool -> [String] -> [String] commandsListExtractCommands addonsonly l =-  [ w | c:ws@(d:_) <- takeWhile (not . isInfixOf "HELP") $ dropWhile (not . isInfixOf "Usage:") l-  , c `elem` '+':[' '|not addonsonly]-  , isAlphaNum d-  , not $ "://" `isInfixOf` ws-  , let w:_ = words ws+  [ cmdname | prefixchar:line@(firstchar:_) <- +      takeWhile (not . isInfixOf "OTHER") $ dropWhile (not . isInfixOf "Usage:") l+  , prefixchar `elem` '+':[' '|not addonsonly]+  , isAlphaNum firstchar+  , not $ "https://" `isInfixOf` line+  , let cmdname:_ = words line   ]+  -- KEEP SYNCED WITH commandsList.  -- | Canonical names of all commands which have a slot in the commands list, in alphabetical order. -- These include the builtin commands and the known addon commands.

@@ -48,7 +48,7 @@   ++ flattreeflags False ++   [flagReq  ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "flat mode: omit N leading account name parts"]   )-  [generalflagsgroup1]+  cligeneralflagsgroups1   hiddenflags   ([], Just $ argsFlag "[QUERY]") 

@@ -1,6 +1,6 @@ accounts -Show account names.+List account names.  _FLAGS 

@@ -19,7 +19,7 @@ activitymode = hledgerCommandMode   $(embedFileRelative "Hledger/Cli/Commands/Activity.txt")   []-  [generalflagsgroup1]+  cligeneralflagsgroups1   hiddenflags   ([], Just $ argsFlag "[QUERY]") 

@@ -1,7 +1,6 @@ add -Prompt for transactions and add them to the journal. Any arguments will-be used as default inputs for the first N prompts.+Record new transactions with interactive prompting in the console.  _FLAGS @@ -36,35 +35,27 @@ -   Input prompts are displayed in a different colour when the terminal     supports it. -Example (see https://hledger.org/add.html for a detailed tutorial):+Notes: -$ hledger add-Adding transactions to journal file /src/hledger/examples/sample.journal-Any command line arguments will be used as defaults.-Use tab key to complete, readline keys to edit, enter to accept defaults.-An optional (CODE) may follow transaction dates.-An optional ; COMMENT may follow descriptions or amounts.-If you make a mistake, enter < at any prompt to go one step backward.-To end a transaction, enter . when prompted.-To quit, enter . at a date prompt or press control-d or control-c.-Date [2015/05/22]: -Description: supermarket-Account 1: expenses:food-Amount  1: $10-Account 2: assets:checking-Amount  2 [$-10.0]: -Account 3 (or . or enter to finish this transaction): .-2015/05/22 supermarket-    expenses:food             $10-    assets:checking        $-10.0+-   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. -Save this transaction to the journal ? [y]: -Saved.-Starting the next transaction (. or ctrl-D/ctrl-C to quit)-Date [2015/05/22]: <CTRL-D> $+Examples: -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.+-   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.

@@ -61,7 +61,7 @@   ,outputFormatFlag ["txt","html","csv","tsv","json"]   ,outputFileFlag   ])-  [generalflagsgroup1]+  cligeneralflagsgroups1   hiddenflags   ([], Just $ argsFlag "ACCTPAT [QUERY]") 

@@ -2,8 +2,8 @@  (areg) -Show the transactions and running historical balance of a single-account, with each transaction displayed as one line.+Show the transactions and running balances in one account, with each+transaction on one line.  _FLAGS 

@@ -336,7 +336,7 @@     ,outputFileFlag     ]   )-  [generalflagsgroup1]+  cligeneralflagsgroups1   (hiddenflags ++     [ flagNone ["commodity-column"] (setboolopt "commodity-column")       "show commodity symbols in a separate column, amounts as bare numbers, one row per commodity"

@@ -2,7 +2,9 @@  (bal) -Show accounts and their balances.+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 @@ -336,6 +338,9 @@ -   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:

@@ -2,17 +2,19 @@  (bs) -This command displays a balance sheet, showing historical ending-balances of asset and liability accounts. (To see equity as well, use-the balancesheetequity command.) Amounts are shown with normal positive-sign, as in conventional financial statements.+Show the end balances in asset and liability accounts. Amounts are shown+with normal positive sign, as in conventional financial statements.  _FLAGS -This report shows accounts declared with the Asset, Cash or Liability-type (see account types). Or if no such accounts are declared, it shows-top-level accounts named asset or liability (case insensitive, plurals-allowed) and their subaccounts.+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: 

@@ -11,7 +11,7 @@  import Data.Char (toLower) import Data.Either (partitionEithers)-import Data.List (isPrefixOf, find)+import Data.List (isPrefixOf, find, sort) import Control.Monad (forM_) import System.Console.CmdArgs.Explicit @@ -22,7 +22,7 @@ checkmode = hledgerCommandMode   $(embedFileRelative "Hledger/Cli/Commands/Check.txt")   []-  [generalflagsgroup1]+  cligeneralflagsgroups1   hiddenflags   ([], Just $ argsFlag "[CHECKS]") @@ -36,7 +36,7 @@    case partitionEithers (map parseCheckArgument args) of     (unknowns@(_:_), _) -> error' $ "These checks are unknown: "++unwords unknowns-    ([], checks) -> forM_ checks $ runCheck copts' j+    ([], checks) -> forM_ (sort checks) $ runCheck copts' j        -- | Regenerate this CliOpts' report specification, after updating its -- underlying report options with the given update function.@@ -49,26 +49,25 @@     Right rs -> copts{reportspec_=rs}  -- | A type of error check that we can perform on the data.--- Some of these imply other checks that are done first,--- eg currently Parseable and Autobalanced are always done,--- and Assertions are always done unless -I is in effect.+-- If performing multiple checks, they will be performed in the order defined here, generally.+-- (We report only the first failure, so the more useful checks should come first.) data Check =+  -- keep the order here synced with Check.md and Hledger.Data.JournalChecks.journalStrictChecks.   -- done always     Parseable   | Autobalanced-  -- done always unless -I is used-  | Assertions-  -- done when -s is used, or on demand by check-  | Accounts-  | Commodities+  | Assertions  -- unless -I is used+  -- done when --strict is used, or when specified with the check command   | Balanced-  -- done on demand by check+  | Commodities+  | Accounts+  -- done when specified with the check command   | Ordereddates   | Payees-  | Recentassertions   | Tags+  | Recentassertions   | Uniqueleafnames-  deriving (Read,Show,Eq,Enum,Bounded)+  deriving (Read,Show,Eq,Enum,Bounded,Ord)  -- | Parse the name (or a name prefix) of an error check, or return the name unparsed. -- Check names are conventionally all lower case, but this parses case insensitively.@@ -93,19 +92,22 @@ -- | Run the named error check, possibly with some arguments,  -- on this journal with these options. runCheck :: CliOpts -> Journal -> (Check,[String]) -> IO ()-runCheck CliOpts{reportspec_=ReportSpec{_rsReportOpts=ropts}} j (chck,_) = do+runCheck _opts j (chck,_) = do   d <- getCurrentDay   let     results = case chck of+      -- these checks are assumed to have passed earlier during journal parsing (if enabled):+      Parseable       -> Right ()+      Autobalanced    -> Right ()+      Balanced        -> Right ()+      Assertions      -> Right ()       Accounts        -> journalCheckAccounts j       Commodities     -> journalCheckCommodities j-      Ordereddates    -> journalCheckOrdereddates (whichDate ropts) j+      Ordereddates    -> journalCheckOrdereddates j       Payees          -> journalCheckPayees j       Recentassertions -> journalCheckRecentAssertions d j       Tags            -> journalCheckTags j       Uniqueleafnames -> journalCheckUniqueleafnames j-      -- the other checks have been done earlier during withJournalDo-      _               -> Right ()    case results of     Right () -> return ()

@@ -4,91 +4,102 @@  _FLAGS -hledger provides a number of built-in error checks to help prevent-problems in your data. Some of these are run automatically; or, you can-use this check command to run them on demand, with no output and a zero-exit code if all is well. Specify their names (or a prefix) as-argument(s).--Some examples:+hledger 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      # basic checks-hledger check -s   # basic + strict checks-hledger check ordereddates payees  # basic + two other checks+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:+Here are the checks currently available. Generally, they are performed+in the order they are shown here (and only the first failure is+reported). -Default checks+Basic checks -These checks are run automatically by (almost) all hledger commands:+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.+    errors and no invalid include directives. This ensures that all+    files exist and are readable. --   autobalanced - all transactions are balanced, after converting to-    cost. Missing amounts and missing costs are inferred automatically-    where possible.+-   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.-    (This check can be disabled with -I/--ignore-assertions.)+    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).  Strict checks -These additional checks are run when the -s/--strict (strict mode) flag-is used. Or, they can be run by giving their names as arguments to-check:+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 - all transactions are balanced after converting to cost,-    without inferring missing costs. If conversion costs are required,-    they must be explicit.+-   balanced - like autobalanced, but in conversion transactions, costs+    must be written explicitly. This ensures some redundancy in the+    entry, which helps prevent typos. --   accounts - all account names used by transactions have been declared+-   commodities - all commodity symbols used must be declared. This+    guards against mistyping or omitting commodity symbols. --   commodities - all commodity symbols used have been declared+-   accounts - all account names used must be declared. This prevents+    the use of mis-spelled or outdated account names.  Other checks -These checks can be run only by giving their names as arguments to-check. They are more specialised and not desirable for everyone:+These other checks are not wanted by everyone, but can be run using the+check command: --   ordereddates - transactions are ordered by date within each file+-   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 have been declared+-   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. --   recentassertions - all accounts with balance assertions have a-    balance assertion within 7 days of their latest posting+-   tags - all tags used by transactions must be declared. This prevents+    mistyped tag names. --   tags - all tags used by transactions have been declared+-   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 - all account leaf names are unique+-   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.  Custom checks -A few more checks are are available as separate add-on commands, in-https://github.com/simonmichael/hledger/tree/master/bin:+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--You could make similar scripts to perform your own custom checks. See:-Cookbook -> Scripting.--More about specific checks--hledger check recentassertions will complain if any balance-asserted-account has postings more than 7 days after its latest balance-assertion. This aims to prevent the situation where you are regularly-updating your journal, but forgetting to check your balances against the-real world, then one day must dig back through months of data to find an-error. It assumes that adding a balance assertion requires/reminds you-to check the real-world balance. (That may not be true if you-auto-generate balance assertions from bank data; in that case, I-recommend to import transactions uncleared, and when you manually review-and clear them, also check the latest assertion against the real-world-balance.)

@@ -53,7 +53,7 @@   ,flagReq  ["open-acct"]    (\s opts -> Right $ setopt "open-acct"  s opts) "ACCT" "set opening transaction's source account"   ,roundFlag   ]-  [generalflagsgroup1]+  cligeneralflagsgroups1   (hiddenflags     ++  -- keep supporting old flag names for compatibility     [flagNone ["closing"]   (setboolopt "close")                                   "old spelling of --close"

@@ -26,7 +26,7 @@ codesmode = hledgerCommandMode   $(embedFileRelative "Hledger/Cli/Commands/Codes.txt")   []-  [generalflagsgroup1]+  cligeneralflagsgroups1   hiddenflags   ([], Just $ argsFlag "[QUERY]") 

@@ -25,7 +25,7 @@ descriptionsmode = hledgerCommandMode   $(embedFileRelative "Hledger/Cli/Commands/Descriptions.txt")   []-  [generalflagsgroup1]+  cligeneralflagsgroups1   hiddenflags   ([], Just $ argsFlag "[QUERY]") 

@@ -32,13 +32,14 @@  helpmode = hledgerCommandMode   $(embedFileRelative "Hledger/Cli/Commands/Help.txt")-  [flagNone ["i"]  (setboolopt "info")  "show the manual with info"-  ,flagNone ["m"]   (setboolopt "man")   "show the manual with man"-  ,flagNone ["p"] (setboolopt "pager") "show the manual with $PAGER or less"-  ,flagNone ["help","h"]  (setboolopt "help")  "show this help"+  [flagNone ["i"] (setboolopt "info")  "show the manual with info"+  ,flagNone ["m"] (setboolopt "man")   "show the manual with man"+  ,flagNone ["p"] (setboolopt "pager") "show the manual with $PAGER or less\n(less is always used if TOPIC is specified)"   ]-  []-  []+  [(helpflagstitle, helpflags)]+  [+    flagReq  ["debug"]    (\s opts -> Right $ setopt "debug" s opts) "[N]" "show debug output (levels 1-9, default: 1)"+  ]   ([], Just $ argsFlag "[TOPIC]")  -- | Display the hledger manual in various formats.

@@ -1,31 +1,31 @@ help -Show the hledger user manual in the terminal, with info, man, or a-pager. With a TOPIC argument, open it at that topic if possible. TOPIC-can be any heading in the manual, or a heading prefix, case insensitive.-Eg: commands, print, forecast, journal, amount, "auto postings".+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 -This command shows the hledger manual built in to your hledger version.-It can be useful when offline, or when you prefer the terminal to a web-browser, or when the appropriate hledger manual or viewing tools are not-installed on your system.+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. You can force the use of info,-man, or a pager with the -i, -m, or -p flags, If no viewer can be found,-or the command is run non-interactively, it just prints the manual to-stdout.+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. -If using info, note that version 6 or greater is needed for TOPIC-lookup. If you are on mac you will likely have info 4.8, and should-consider installing a newer version, eg with brew install texinfo-(#1770).+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 --help      # show how the help command works-$ hledger help             # show the hledger manual with info, man or $PAGER-$ hledger help journal     # show the journal topic in the hledger manual-$ hledger help -m journal  # show it with man, even if info is installed+$ 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

@@ -24,7 +24,7 @@   [flagNone ["catchup"] (setboolopt "catchup") "just mark all transactions as already imported"   ,flagNone ["dry-run"] (setboolopt "dry-run") "just show the transactions to be imported"   ]-  [generalflagsgroup1]+  cligeneralflagsgroups1   hiddenflags   ([], Just $ argsFlag "FILE [...]") 

@@ -1,27 +1,29 @@ import -Read new transactions added to each FILE provided as arguments since-last run, and add them to the journal. Or with --dry-run, just print the-transactions that would be added. Or with --catchup, just mark all of-the FILEs' current transactions as imported, without importing them.+Import new transactions from one or more data files to the main journal.  _FLAGS -This command may append new transactions to the main journal file (which-should be in journal format). Existing transactions are not changed.+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).+(see also add). It only appends; existing data will not be changed. -Unlike other hledger commands, with import the journal file is an output-file, and will be modified, though only by appending (existing data will-not be changed). The input files are specified as arguments, so to-import one or more CSV files to your main journal, you will run-hledger import bank.csv or perhaps hledger import *.csv.+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.+common import source, and these docs focus on that case. The target file+(main journal) should be in journal format. -Deduplication+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@@ -29,53 +31,55 @@ 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 (usually CSV, but they could-be any of hledger's input formats):+It works as follows: for each imported FILE, --   It tries to recall the latest date seen previously, reading it from-    a hidden .latest.FILE in the same directory.--   Then it processes FILE, ignoring any transactions on or before the-    "latest seen" date.+-   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, it updates the .latest.FILE(s) for next-time (unless --dry-run was used).+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: -This is a limited kind of deduplication, let's call it "date skipping".-Within each input file, it avoids reprocessing the same dates across-successive runs. This is a simple system that works for most real-world-CSV files; it assumes these 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. -1.  new items always have the newest dates-2.  item dates are stable across successive downloads-3.  the order of same-date items is stable across downloads-4.  the name of the input file is stable across downloads+Tips: -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, and in old transactions it doesn't matter. And remember you-can use CSV rules files as input, which is one way to ensure a stable-file name.+-   To help ensure a stable file name, remember you can use a CSV rules+    file as an input file. -import doesn't detect other kinds of duplication, such as duplicate-transactions within a single run. (In part, because legitimate duplicate-transactions can easily occur in real-world data.) So, say you-downloaded but forgot to import bank.1.csv, and a week later you-downloaded bank.2.csv with overlapping data. Now you should not import-both of these at once (hledger import bank.1.csv bank.2.csv); the-overlapping transactions which appear twice would not be deduplicated-since this is considered a single import. Instead, import these files-one at a time, and also use the same filename each time for a common-"latest seen" state:+-   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 can ignore the .latest.* files, but if needed, you can-delete them (to make all transactions unseen), or construct/modify them-(to catch up to a certain date). The format is just a single ISO-format-date (YYYY-MM-DD), possibly repeated on multiple lines. It means "I have-seen transactions up to this date, and this many of them occurring on-that date".+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.@@ -118,7 +122,10 @@ (If you think import should leave amounts implicit like print does, please test it and send a pull request.) -Commodity display styles+Import and commodity styles -Imported amounts will be formatted according to the canonical commodity-styles (declared or inferred) in the main journal file.+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.

@@ -2,16 +2,19 @@  (is) -This command displays an income statement, showing revenues and expenses-during one or more periods. Amounts are shown with normal positive sign,-as in conventional financial statements.+Show revenue inflows and expense outflows during the report period.+Amounts are shown with normal positive sign, as in conventional+financial statements.  _FLAGS -This report shows accounts declared with the Revenue or Expense type-(see account types). Or if no such accounts are declared, it shows-top-level accounts named revenue or income or expense (case insensitive,-plurals allowed) and their subaccounts.+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: 

@@ -26,7 +26,7 @@ notesmode = hledgerCommandMode   $(embedFileRelative "Hledger/Cli/Commands/Notes.txt")   []-  [generalflagsgroup1]+  cligeneralflagsgroups1   hiddenflags   ([], Just $ argsFlag "[QUERY]") 

@@ -28,7 +28,7 @@   [flagNone ["declared"] (setboolopt "declared") "show payees declared with payee directives"   ,flagNone ["used"] (setboolopt "used") "show payees referenced by transactions"   ]-  [generalflagsgroup1]+  cligeneralflagsgroups1   hiddenflags   ([], Just $ argsFlag "[QUERY]") 

@@ -22,7 +22,7 @@   [flagNone ["show-reverse"] (setboolopt "show-reverse")     "also show the prices inferred by reversing known prices"   ]-  [generalflagsgroup1]+  cligeneralflagsgroups1   (hiddenflags ++   [flagNone ["costs"]                (setboolopt "infer-market-prices") "deprecated, use --infer-market-prices instead"   ,flagNone ["inverted-costs"]       (setboolopt "show-reverse") "deprecated, use --show-reverse instead"

@@ -51,7 +51,7 @@   ,outputFormatFlag ["txt","beancount","csv","tsv","json","sql"]   ,outputFileFlag   ])-  [generalflagsgroup1]+  cligeneralflagsgroups1   hiddenflags   ([], Just $ argsFlag "[QUERY]") 

@@ -1,6 +1,6 @@ print -Show transaction journal entries, sorted by date.+Show full journal entries, representing transactions.  _FLAGS 

@@ -62,7 +62,7 @@   ,outputFormatFlag ["txt","csv","tsv","json"]   ,outputFileFlag   ])-  [generalflagsgroup1]+  cligeneralflagsgroups1   hiddenflags   ([], Just $ argsFlag "[QUERY]") 

@@ -29,7 +29,7 @@            "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."   ,flagNone ["diff"] (setboolopt "diff") "generate diff suitable as an input for patch tool"   ]-  [generalflagsgroup1]+  cligeneralflagsgroups1   hiddenflags   ([], Just $ argsFlag "[QUERY] --add-posting \"ACCT  AMTEXPR\" ...") 

@@ -44,7 +44,7 @@   ,flagReq ["profit-loss","pnl"] (\s opts -> Right $ setopt "pnl" s opts) "QUERY"     "query to select profit-and-loss or appreciation/valuation transactions"   ]-  [generalflagsgroup1]+  cligeneralflagsgroups1   hiddenflags   ([], Just $ argsFlag "[QUERY]") 

@@ -43,7 +43,7 @@   [ flagNone ["verbose","v"]    (setboolopt "verbose") "show more detailed output"   ,flagReq  ["output-file","o"] (\s opts -> Right $ setopt "output-file" s opts) "FILE" "write output to FILE."   ]-  [generalflagsgroup1]+  cligeneralflagsgroups1   hiddenflags   ([], Just $ argsFlag "[QUERY]") 

@@ -21,7 +21,7 @@   [flagNone ["values"] (setboolopt "values") "list tag values instead of tag names"   ,flagNone ["parsed"] (setboolopt "parsed") "show tags/values in the order they were parsed, including duplicates"   ]-  [generalflagsgroup1]+  cligeneralflagsgroups1   hiddenflags   ([], Just $ argsFlag "[TAGREGEX [QUERY...]]") 

@@ -97,7 +97,7 @@     ,outputFormatFlag ["txt","html","csv","tsv","json"]     ,outputFileFlag     ])-    [generalflagsgroup1]+    cligeneralflagsgroups1     (hiddenflags ++       [ flagNone ["commodity-column"] (setboolopt "commodity-column")         "show commodity symbols in a separate column, amounts as bare numbers, one row per commodity"

@@ -1,4 +1,4 @@-{-# LANGUAGE TemplateHaskell, OverloadedStrings, PackageImports #-}+{-# LANGUAGE TemplateHaskell, OverloadedStrings, PackageImports, ScopedTypeVariables #-} {-|  Embedded documentation files in various formats, and helpers for viewing them.@@ -8,27 +8,24 @@ module Hledger.Cli.DocFiles (     Topic-  -- ,toolDocs-  -- ,toolDocNames-  -- ,toolDocMan-  -- ,toolDocTxt-  -- ,toolDocInfo   ,printHelpForTopic   ,runManForTopic   ,runInfoForTopic   ,runPagerForTopic+  ,runTldrForPage    ) where +import Control.Exception import Data.ByteString (ByteString) import qualified Data.ByteString.Char8 as BC-import Data.Maybe (fromMaybe, isNothing)+import Data.Maybe (fromMaybe) import Data.String import System.IO import System.IO.Temp import System.Process -import Hledger.Utils (first3, second3, third3, embedFileRelative)+import Hledger.Utils (first3, second3, third3, embedFileRelative, error') import Text.Printf (printf) import System.Environment (lookupEnv) import Hledger.Utils.Debug@@ -39,11 +36,30 @@ -- Any heading in the hledger user manual (and perhaps later the hledger-ui/hledger-web manuals). type Topic = String +-- Any name of a hledger tldr page (hledger, hledger-ui, hledger-print etc.)+type TldrPage = String++-- | All hledger-related pages from the tldr-pages project.+-- All are symlinked into the hledger package directory to allow embeddeding.+tldrs :: [(TldrPage, ByteString)]+tldrs = [+   ("hledger-accounts",        $(embedFileRelative "embeddedfiles/hledger-accounts.md"))+  ,("hledger-add",             $(embedFileRelative "embeddedfiles/hledger-add.md"))+  ,("hledger-aregister",       $(embedFileRelative "embeddedfiles/hledger-aregister.md"))+  ,("hledger-balance",         $(embedFileRelative "embeddedfiles/hledger-balance.md"))+  ,("hledger-balancesheet",    $(embedFileRelative "embeddedfiles/hledger-balancesheet.md"))+  ,("hledger-import",          $(embedFileRelative "embeddedfiles/hledger-import.md"))+  ,("hledger-incomestatement", $(embedFileRelative "embeddedfiles/hledger-incomestatement.md"))+  ,("hledger-print",           $(embedFileRelative "embeddedfiles/hledger-print.md"))+  ,("hledger-ui",              $(embedFileRelative "embeddedfiles/hledger-ui.md"))+  ,("hledger-web",             $(embedFileRelative "embeddedfiles/hledger-web.md"))+  ,("hledger",                 $(embedFileRelative "embeddedfiles/hledger.md"))+  ]+ -- | The main hledger manuals as source for man, info and as plain text.--- Only files under the current package directory can be embedded,--- so some of these are symlinked from the other package directories.-toolDocs :: [(Tool, (ByteString, ByteString, ByteString))]-toolDocs = [+-- All are symlinked into the hledger package directory to allow embeddeding.+manuals :: [(Tool, (ByteString, ByteString, ByteString))]+manuals = [    ("hledger",     ($(embedFileRelative "embeddedfiles/hledger.1")     ,$(embedFileRelative "embeddedfiles/hledger.txt")@@ -61,73 +77,85 @@     ))   ] --- toolNames :: [Tool]--- toolNames = map fst toolDocs- -- | Get the manual as plain text for this tool, or a not found message.-toolDocTxt :: Tool -> ByteString-toolDocTxt name =-  maybe (fromString $ "No text manual found for tool: "++name) second3 $ lookup name toolDocs+manualTxt :: Tool -> ByteString+manualTxt name = maybe (fromString $ "No text manual found for tool: "++name) second3 $ lookup name manuals  -- | Get the manual as man source (nroff) for this tool, or a not found message.-toolDocMan :: Tool -> ByteString-toolDocMan name =-  maybe (fromString $ "No man page found for tool: "++name) first3 $ lookup name toolDocs+manualMan :: Tool -> ByteString+manualMan name = maybe (fromString $ "No man page found for tool: "++name) first3 $ lookup name manuals  -- | Get the manual as info source (texinfo) for this tool, or a not found message.-toolDocInfo :: Tool -> ByteString-toolDocInfo name =-  maybe (fromString $ "No info manual found for tool: "++name) third3 $ lookup name toolDocs+manualInfo :: Tool -> ByteString+manualInfo name = maybe (fromString $ "No info manual found for tool: "++name) third3 $ lookup name manuals  -- | Print plain text help for this tool. -- Takes an optional topic argument for convenience but it is currently ignored. printHelpForTopic :: Tool -> Maybe Topic -> IO ()-printHelpForTopic tool _mtopic =-  BC.putStr (toolDocTxt tool)+printHelpForTopic tool _mtopic = BC.putStr (manualTxt tool) --- | Display plain text help for this tool, scrolled to the given topic--- if provided, using the given pager executable.--- Note when a topic is provided we ignore the provided pager and--- use the "less" executable in $PATH.+-- | Display an info manual for this topic, opened at the given topic if provided,+-- using the "info" executable in $PATH.+-- Topic can be an exact heading or a heading prefix; info will favour an exact match.+runInfoForTopic :: Tool -> Maybe Topic -> IO ()+runInfoForTopic tool mtopic =+  withSystemTempFile ("hledger-"++tool++".info") $ \f h -> do+    BC.hPutStrLn h $ manualInfo tool+    hClose h+    callCommand $ dbg1 "info command" $+      "info -f " ++ f ++ maybe "" (printf " -n '%s'") mtopic++-- less with any vertical whitespace squashed, case-insensitive searching, the $ regex metacharacter accessible as \$.+less = "less -s -i --use-backslash"++-- | Display plain text help for this tool, scrolled to the given topic if any, using the users $PAGER or "less".+-- When a topic is provided we always use less, ignoring $PAGER. runPagerForTopic :: Tool -> Maybe Topic -> IO () runPagerForTopic tool mtopic = do-  -- avoids a temp file but different from the others and not sure how to make it scroll-  -- pager <- fromMaybe "less" <$> lookupEnv "PAGER"-  -- (Just inp, _, _, ph) <- createProcess (proc pager []){-  --   std_in=CreatePipe-  --   }-  -- BC.hPutStrLn inp (toolDocTxt tool)-  -- _ <- waitForProcess ph-  -- return ()-     withSystemTempFile ("hledger-"++tool++".txt") $ \f h -> do-    BC.hPutStrLn h $ toolDocTxt tool+    BC.hPutStrLn h $ manualTxt tool     hClose h-    let defpager = "less -is"-    envpager <- fromMaybe defpager <$> lookupEnv "PAGER"-    -- force the use of less if a topic is provided, since we know how to scroll it-    let pager = if isNothing mtopic then envpager else defpager-    callCommand $ dbg1 "pager command" $ -      pager ++ maybe "" (printf " +'/^(   )?%s'") mtopic ++ " " ++ f+    envpager <- fromMaybe less <$> lookupEnv "PAGER"+    let+      exactmatch = True+      (pager, searcharg) =+        case mtopic of+          Nothing -> (envpager, "")+          Just t  -> (less, "-p'^(   )?" ++ t ++ if exactmatch then "\\$'" else "")+    callCommand $ dbg1 "pager command" $ unwords [pager, searcharg, f] --- | Display a man page for this tool, scrolled to the given topic if provided, --- using the "man" executable in $PATH. Note when a topic is provided we force --- man to use the "less" executable in $PATH, ignoring $MANPAGER and $PAGER.+-- | Display a man page for this tool, scrolled to the given topic if provided, using "man".+-- When a topic is provided we force man to use "less", ignoring $MANPAGER and $PAGER. runManForTopic :: Tool -> Maybe Topic -> IO () runManForTopic tool mtopic =-  withSystemTempFile ("hledger-"++tool++".nroff") $ \f h -> do-    BC.hPutStrLn h $ toolDocMan tool+  -- This temp file path should have a slash in it, man requires at least one.+  withSystemTempFile ("hledger-"++tool++".1") $ \f h -> do+    BC.hPutStrLn h $ manualMan tool     hClose h-    -- the temp file path will presumably have a slash in it, so man should read it-    callCommand $ dbg1 "man command" $ -      "man " ++ f ++ maybe "" (printf " -P \"less -is +'/^(   )?%s'\"") mtopic+    let+      exactmatch = True+      pagerarg =+        case mtopic of+          Nothing -> ""+          Just t  -> "-P \"" ++ less ++ " -p'^(   )?" ++ t ++ (if exactmatch then "\\\\$" else "") ++ "'\""+    callCommand $ dbg1 "man command" $ unwords ["man", pagerarg, f] --- | Display an info manual for this topic, opened at the given topic if provided,--- using the "info" executable in $PATH.-runInfoForTopic :: Tool -> Maybe Topic -> IO ()-runInfoForTopic tool mtopic =-  withSystemTempFile ("hledger-"++tool++".info") $ \f h -> do-    BC.hPutStrLn h $ toolDocInfo tool-    hClose h-    callCommand $ dbg1 "info command" $-      "info -f " ++ f ++ maybe "" (printf " -n '%s'") mtopic+-- | Get the named tldr page's source, if we know it.+tldr :: TldrPage -> Maybe ByteString+tldr name = lookup name tldrs++-- | 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]+      ) `catch` (\(_e::IOException) -> do+        hPutStrLn stderr $ "Could not run " <> tldrprog <> ", using fallback viewer:\n"+        BC.putStrLn b+      )

@@ -9,7 +9,6 @@   VersionString,   packageversion,   packagemajorversion,-  progname,   versionStringWith, ) where@@ -19,7 +18,7 @@ import Data.List (intercalate) import Data.Maybe (fromMaybe) -import Hledger.Utils (splitAtElement)+import Hledger.Utils (ghcDebugSupportedInLib, splitAtElement)  type ProgramName    = String type PackageVersion = String@@ -39,13 +38,9 @@ packagemajorversion :: PackageVersion packagemajorversion = intercalate "." $ take 2 $ splitAtElement '.' packageversion --- | The name of this package's main executable.-progname :: ProgramName-progname = "hledger"---- | Given possible git state info from the build directory (or an error message, which is ignored),--- the name of a program (executable) in the currently building package,--- and the package's version, make a complete version string. Here is the logic:+-- | Given possible git state info from the build directory (or a git error, which is ignored),+-- and the ghcdebug build flag, executable name and package version for the package being built,+-- make the best version string we can. Here is the logic: --  -- * Program name, OS and architecture are always shown. -- * The package version is always shown.@@ -55,6 +50,8 @@ -- * (TODO, requires adding --match support to githash: --   If there are tags matching THISPKG-[0-9]*, the latest one is used to calculate patch level --   (number of commits since tag), and if non-zero, it and the branch name are shown.)+-- * If the ghcdebug build flag was enabled for the package being built, and for hledger-lib (both are needed),+--   "ghc-debug support" is shown. -- -- Some example outputs: --@@ -65,9 +62,19 @@ -- This function requires git log to show the default (rfc2822-style) date format, -- so that must not be overridden by a log.date git config variable. ---versionStringWith :: Either String GitInfo -> ProgramName -> PackageVersion -> VersionString-versionStringWith egitinfo prognam packagever =-  concat [ prognam , " " , version , ", " , os' , "-" , arch ]+-- The GitInfo if any, fetched by template haskell, is passed down from+-- a top-level module, reducing wasteful recompilation.+-- The status of the ghcdebug build flag is also passed down, since it is+-- specific to each hledger package.+--+-- This is used indirectly by at least hledger, hledger-ui, and hledger-web,+-- so output should be suitable for all of those.+--+versionStringWith :: Either String GitInfo -> Bool -> ProgramName -> PackageVersion -> VersionString+versionStringWith egitinfo ghcDebugSupportedInThisPackage progname packagever =+  concat $+    [ progname , " " , version , ", " , os' , "-" , arch ]+    ++ [ " with ghc-debug support" | ghcDebugSupportedInThisPackage && ghcDebugSupportedInLib ]   where     os' | os == "darwin"  = "mac"         | os == "mingw32" = "windows"@@ -102,14 +109,3 @@                     dd = (if length day < 2 then ('0':) else id) day           -- but could be overridden by a log.date config variable in repo or user git config           _ -> packageversion---- -- | Given a program name, return a precise platform-specific executable--- -- name suitable for naming downloadable binaries.  Can raise an error if--- -- the version and patch level was not defined correctly at build time.--- binaryfilename :: String -> String--- binaryfilename progname = concat---     [progname, "-", buildversion, "-", os', "-", arch, suffix]---   where---     (os',suffix) | os == "darwin"  = ("mac","" :: String)---                  | os == "mingw32" = ("windows",".exe")---                  | otherwise       = (os,"")

@@ -0,0 +1,36 @@+# hledger accounts++> List account names.+> More information: <https://hledger.org/hledger.html#accounts>.++- Show all accounts used or declared in the default journal file:++`hledger accounts`++- Show accounts used by transactions:++`hledger accounts --used`++- Show accounts declared with account directives:++`hledger accounts --declared`++- Add new account directives, for accounts used but not declared, to the journal:++`hledger accounts --undeclared --directives >> {{2024-accounts.journal}}`++- Show accounts with `asset` in their name, and their declared/inferred types:++`hledger accounts asset --types`++- Show accounts of the `Asset` type:++`hledger accounts type:A`++- Show the first two levels of the accounts hierarchy:++`hledger accounts --tree --depth 2`++- Short form of the above:++`hledger acc -t -2`

@@ -0,0 +1,24 @@+# hledger add++> Record new transactions with interactive prompting in the console.+> More information: <https://hledger.org/hledger.html#add>.++- 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 {{path/to/2024.journal}} --file {{path/to/2023.journal}}`++- Provide answers for the first four prompts:++`hledger add {{today}} '{{best buy}}' {{expenses:supplies}} '{{$20}}'`++- Show `add`'s options and documentation with `$PAGER`:++`hledger add --help`++- Show `add`'s documentation with `info` or `man` if available:++`hledger help add`

@@ -0,0 +1,20 @@+# hledger aregister++> Show the transactions and running balances in one account, with each transaction on one line.+> More information: <https://hledger.org/hledger.html#aregister>.++- Show transactions and running balance in the `assets:bank:checking` account:++`hledger aregister assets:bank:checking`++- Show transactions and running balance in the first account named `*savings*`:++`hledger aregister savings`++- Show the checking account's cleared transactions, with a specified width:++`hledger aregister checking --cleared --width {{120}}`++- Show the checking register, including transactions from forecast rules:++`hledger aregister checking --forecast`

@@ -0,0 +1,37 @@+# hledger balance++> 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.+> More information: <https://hledger.org/hledger.html#balance>.++- Show the balance change in all accounts from all postings over all time:++`hledger balance`++- Show the balance change in accounts named `*expenses*`, as a tree, summarising the top two levels only:++`hledger balance {{expenses}} --tree --depth {{2}}`++- Show expenses each month, and their totals and averages, sorted by total; and their monthly budget goals:++`hledger balance {{expenses}} --monthly --row-total --average --sort-amount --budget`++- Similar to the above, shorter form, matching accounts by `Expense` type, as a two level tree without squashing boring accounts:++`hledger bal type:{{X}} -MTAS --budget -t -{{2}} --no-elide`++- Show end balances (including from postings before the start date), quarterly in 2024, in accounts named `*assets*` or `*liabilities*`:++`hledger balance --historical --period '{{quarterly in 2024}}' {{assets}} {{liabilities}}`++- Similar to the above, shorter form; also show zero balances, sort by total and summarise to three levels:++`hledger bal -HQ date:{{2024}} type:{{AL}} -ES -{{3}}`++- Show investment assets' market value in base currency at the end of each quarter:++`hledger bal -HVQ {{assets:investments}}`++- Show unrealised capital gains/losses from market price changes in each quarter, for non-cryptocurrency investment assets:++`hledger bal --gain -Q {{assets:investments}} not:{{cryptocurrency}}`

@@ -0,0 +1,33 @@+# hledger balancesheet++> Show the end balances in asset and liability accounts.+> Amounts are shown with normal positive sign, as in conventional financial statements.+> More information: <https://hledger.org/hledger.html#balancesheet>.++- Show the current balances in `Asset` and `Liability` accounts, excluding zeros:++`hledger balancesheet`++- Show just the liquid assets (`Cash` account type):++`hledger balancesheet type:C`++- Include accounts with zero balances, and show the account hierarchy:++`hledger balancesheet --empty --tree`++- Show the balances at the end of each month:++`hledger balancesheet --monthly`++- Show the balances' market value in home currency at the end of each month:++`hledger balancesheet --monthly -V`++- Show quarterly balances, with just the top two levels of account hierarchy:++`hledger balancesheet --quarterly --tree --depth 2`++- Short form of the above, and generate HTML output in `bs.html`:++`hledger bs -Qt -2 -o bs.html`

@@ -0,0 +1,28 @@+# hledger import++> Import new transactions from one or more data files to the main journal.+> More information: <https://hledger.org/hledger.html#import>.++- Import new transactions from `bank.csv`, using `bank.csv.rules` to convert:++`hledger import {{path/to/bank.csv}}`++- Show what would be imported from these two files, without doing anything:++`hledger import {{path/to/bank1.csv}} {{path/to/bank2.csv}} --dry-run`++- Import new transactions from all CSV files, using the same rules for all:++`hledger import --rules-file {{common.rules}} *.csv`++- Show conversion errors or results while editing `bank.csv.rules`:++`watchexec -- hledger -f {{path/to/bank.csv}} print`++- Mark `bank.csv`'s current data as seen, as if already imported:++`hledger import --catchup {{path/to/bank.csv}}`++- Mark `bank.csv` as all new, as if not yet imported:++`rm -f .latest.bank.csv`

@@ -0,0 +1,21 @@+# hledger incomestatement++> Show revenue inflows and expense outflows during the report period.+> Amounts are shown with normal positive sign, as in conventional financial statements.+> More information: <https://hledger.org/hledger.html#incomestatement>.++- Show revenues and expenses (changes in `Revenue` and `Expense` accounts):++`hledger incomestatement`++- Show revenues and expenses each month:++`hledger incomestatement --monthly`++- Show monthly revenues/expenses/totals, largest first, summarised to 2 levels:++`hledger incomestatement --monthly --row-total --average --sort --depth 2`++- Short form of the above, and generate HTML output in `is.html`:++`hledger is -MTAS -2 -o is.html`

@@ -0,0 +1,32 @@+# hledger print++> Show full journal entries, representing transactions.+> More information: <https://hledger.org/hledger.html#print>.++- Show all transactions in the default journal file:++`hledger print`++- Show transactions, with any implied amounts or costs made explicit:++`hledger print --explicit --infer-costs`++- Show transactions from two specified files, with amounts converted to cost:++`hledger print --file {{path/to/2023.journal}} --file {{path/to/2024.journal}} --cost`++- Show `$` transactions in `*food*` but not `*groceries*` accounts this month:++`hledger print cur:\\$ food not:groceries date:thismonth`++- Show transactions of amount 50 or more, with `whole foods` in their description:++`hledger print amt:'>50' desc:'whole foods'`++- Show cleared transactions, with `EUR` amounts rounded and with decimal commas:++`hledger print --cleared --commodity '1000, EUR' --round hard`++- Write transactions from `foo.journal` as a CSV file:++`hledger print --file {{path/to/foo.journal}} --output-file {{path/to/output_file.csv}}`

@@ -1,18 +1,23 @@ -.TH "HLEDGER\-UI" "1" "May 2024" "hledger-ui-1.33.1 " "hledger User Manuals"+.TH "HLEDGER\-UI" "1" "June 2024" "hledger-ui-1.34 " "hledger User Manuals"    .SH NAME-hledger\-ui \- robust, friendly plain text accounting (TUI version)+hledger\-ui \- terminal interface (TUI) for \f[CR]hledger\f[R], a+robust, friendly plain text accounting app. .SH SYNOPSIS \f[CR]hledger\-ui    [OPTS] [QUERYARGS]\f[R] .PD 0 .P .PD+or+.PD 0+.P+.PD \f[CR]hledger ui \-\- [OPTS] [QUERYARGS]\f[R] .SH DESCRIPTION-This manual is for hledger\[aq]s terminal interface, version 1.33.1.+This manual is for hledger\[aq]s terminal interface, version 1.34. See also the hledger manual for common concepts and file formats. .PP hledger is a robust, user\-friendly, cross\-platform set of programs for@@ -41,203 +46,110 @@ transactions, by pressing the F key (or starting with \-\-forecast) to enable \[dq]forecast mode\[dq]. .SH OPTIONS-Any QUERYARGS are interpreted as a hledger search query which filters-the data.-.PP+Any arguments are interpreted as a hledger query which filters the data. hledger\-ui provides the following options:-.TP-\f[CR]\-w \-\-watch\f[R]-watch for data and date changes and reload automatically-.TP-\f[CR]\-\-theme=default|terminal|greenterm|dark\f[R]-use this custom display theme-.TP-\f[CR]\-\-menu\f[R]-start in the menu screen-.TP-\f[CR]\-\-cash\f[R]-start in the cash accounts screen-.TP-\f[CR]\-\-bs\f[R]-start in the balance sheet accounts screen-.TP-\f[CR]\-\-is\f[R]-start in the income statement accounts screen-.TP-\f[CR]\-\-all\f[R]-start in the all accounts screen-.TP-\f[CR]\-\-register=ACCTREGEX\f[R]-start in the (first) matched account\[aq]s register screen-.TP-\f[CR]\-\-change\f[R]-show period balances (changes) at startup instead of historical balances-.TP-\f[CR]\-l \-\-flat\f[R]-show accounts as a flat list (default)-.TP-\f[CR]\-t \-\-tree\f[R]-show accounts as a tree-.PP-hledger\-ui also supports many of hledger\[aq]s general options (and the-hledger manual\[aq]s command line tips also apply here):-.SS General help options-.TP-\f[CR]\-h \-\-help\f[R]-show general or COMMAND help-.TP-\f[CR]\-\-man\f[R]-show general or COMMAND user manual with man-.TP-\f[CR]\-\-info\f[R]-show general or COMMAND user manual with info-.TP-\f[CR]\-\-version\f[R]-show general or ADDONCMD version-.TP-\f[CR]\-\-debug[=N]\f[R]-show debug output (levels 1\-9, default: 1)-.SS General input options-.TP-\f[CR]\-f FILE \-\-file=FILE\f[R]-use a different input file.-For stdin, use \- (default: \f[CR]$LEDGER_FILE\f[R] or-\f[CR]$HOME/.hledger.journal\f[R])-.TP-\f[CR]\-\-rules\-file=RULESFILE\f[R]-Conversion rules file to use when reading CSV (default: FILE.rules)-.TP-\f[CR]\-\-separator=CHAR\f[R]-Field separator to expect when reading CSV (default: \[aq],\[aq])-.TP-\f[CR]\-\-alias=OLD=NEW\f[R]-rename accounts named OLD to NEW-.TP-\f[CR]\-\-pivot FIELDNAME\f[R]-use some other field or tag for the account name-.TP-\f[CR]\-I \-\-ignore\-assertions\f[R]-disable balance assertion checks (note: does not disable balance-assignments)-.TP-\f[CR]\-s \-\-strict\f[R]-do extra error checking (check that all posted accounts are declared)-.SS General reporting options-.TP-\f[CR]\-b \-\-begin=DATE\f[R]-include postings/txns on or after this date (will be adjusted to-preceding subperiod start when using a report interval)-.TP-\f[CR]\-e \-\-end=DATE\f[R]-include postings/txns before this date (will be adjusted to following-subperiod end when using a report interval)-.TP-\f[CR]\-D \-\-daily\f[R]-multiperiod/multicolumn report by day-.TP-\f[CR]\-W \-\-weekly\f[R]-multiperiod/multicolumn report by week-.TP-\f[CR]\-M \-\-monthly\f[R]-multiperiod/multicolumn report by month-.TP-\f[CR]\-Q \-\-quarterly\f[R]-multiperiod/multicolumn report by quarter-.TP-\f[CR]\-Y \-\-yearly\f[R]-multiperiod/multicolumn report by year-.TP-\f[CR]\-p \-\-period=PERIODEXP\f[R]-set start date, end date, and/or reporting interval all at once using-period expressions syntax-.TP-\f[CR]\-\-date2\f[R]-match the secondary date instead (see command help for other effects)-.TP-\f[CR]\-\-today=DATE\f[R]-override today\[aq]s date (affects relative smart dates, for-tests/examples)-.TP-\f[CR]\-U \-\-unmarked\f[R]-include only unmarked postings/txns (can combine with \-P or \-C)-.TP-\f[CR]\-P \-\-pending\f[R]-include only pending postings/txns-.TP-\f[CR]\-C \-\-cleared\f[R]-include only cleared postings/txns-.TP-\f[CR]\-R \-\-real\f[R]-include only non\-virtual postings-.TP-\f[CR]\-NUM \-\-depth=NUM\f[R]-hide/aggregate accounts or postings more than NUM levels deep-.TP-\f[CR]\-E \-\-empty\f[R]-show items with zero amount, normally hidden (and vice\-versa in-hledger\-ui/hledger\-web)-.TP-\f[CR]\-B \-\-cost\f[R]-convert amounts to their cost/selling amount at transaction time-.TP-\f[CR]\-V \-\-market\f[R]-convert amounts to their market value in default valuation commodities-.TP-\f[CR]\-X \-\-exchange=COMM\f[R]-convert amounts to their market value in commodity COMM-.TP-\f[CR]\-\-value\f[R]-convert amounts to cost or market value, more flexibly than \-B/\-V/\-X-.TP-\f[CR]\-\-infer\-equity\f[R]-infer conversion equity postings from costs-.TP-\f[CR]\-\-infer\-costs\f[R]-infer costs from conversion equity postings-.TP-\f[CR]\-\-infer\-market\-prices\f[R]-use costs as additional market prices, as if they were P directives-.TP-\f[CR]\-\-forecast\f[R]-generate transactions from periodic rules,-between the latest recorded txn and 6 months from today,-or during the specified PERIOD (= is required).-Auto posting rules will be applied to these transactions as well.-Also, in hledger\-ui make future\-dated transactions visible.-.TP-\f[CR]\-\-auto\f[R]-generate extra postings by applying auto posting rules to all txns (not-just forecast txns)-.TP-\f[CR]\-\-verbose\-tags\f[R]-add visible tags indicating transactions or postings which have been-generated/modified-.TP-\f[CR]\-\-commodity\-style\f[R]-Override the commodity style in the output for the specified commodity.-For example \[aq]EUR1.000,00\[aq].-.TP-\f[CR]\-\-color=WHEN (or \-\-colour=WHEN)\f[R]-Should color\-supporting commands use ANSI color codes in text output.-\[aq]auto\[aq] (default): whenever stdout seems to be a-color\-supporting terminal.-\[aq]always\[aq] or \[aq]yes\[aq]: always, useful eg when piping output-into \[aq]less \-R\[aq].-\[aq]never\[aq] or \[aq]no\[aq]: never.-A NO_COLOR environment variable overrides this.-.TP-\f[CR]\-\-pretty[=WHEN]\f[R]-Show prettier output, e.g.-using unicode box\-drawing characters.-Accepts \[aq]yes\[aq] (the default) or \[aq]no\[aq] (\[aq]y\[aq],-\[aq]n\[aq], \[aq]always\[aq], \[aq]never\[aq] also work).-If you provide an argument you must use \[aq]=\[aq], e.g.-\[aq]\-\-pretty=yes\[aq].+.IP+.EX+Flags:+  \-w \-\-watch                watch for data and date changes and reload+                            automatically+     \-\-theme=THEME          use this custom display theme (default,+                            greenterm, terminal, dark)+     \-\-cash                 start in the cash accounts screen+     \-\-bs                   start in the balance sheet accounts screen+     \-\-is                   start in the income statement accounts screen+     \-\-all                  start in the all accounts screen+     \-\-register=ACCTREGEX   start in the (first matched) account\[aq]s register+     \-\-change               show period balances (changes) at startup instead+                            of historical balances+  \-l \-\-flat                 show accounts as a flat list (default)+  \-t \-\-tree                 show accounts as a tree+.EE .PP-When a reporting option appears more than once in the command line, the-last one takes precedence.+and also supports many of hledger\[aq]s general options:+.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+                            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 (\[dq]=\[dq]) to all transactions+     \-\-forecast[=PERIOD]    Generate extra transactions from periodic rules+                            (\[dq]\[ti]\[dq]), 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\[aq]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\[aq]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:+                            \[aq]then\[aq]:     value on transaction dates+                            \[aq]end\[aq]:      value at period end(s)+                            \[aq]now\[aq]:      value today+                            YYYY\-MM\-DD: value on given date+  \-c \-\-commodity\-style=S    Override a commodity\[aq]s display style.+                            Eg: \-c \[aq].\[aq] or \-c \[aq]1.000,00 EUR\[aq]+     \-\-color=YN \-\-colour    Use ANSI color codes in text output? Can be+                            \[aq]y\[aq]/\[aq]yes\[aq]/\[aq]always\[aq], \[aq]n\[aq]/\[aq]no\[aq]/\[aq]never\[aq] or \[aq]auto\[aq].+     \-\-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+     \-\-tldr                 show command examples with tldr+     \-\-info                 show the manual with info+     \-\-man                  show the manual with man+     \-\-version              show version information+.EE .PP-Some reporting options can also be written as query arguments.+With hledger\-ui, the \f[CR]\-\-debug\f[R] option sends debug output to+a \f[CR]hledger\-ui.log\f[R] file in the current directory. .SH MOUSE In most modern terminals, you can navigate through the screens with a mouse or touchpad:@@ -375,32 +287,32 @@ You can also use a command line flag to specific a different startup screen (\f[CR]\-\-cs\f[R], \f[CR]\-\-bs\f[R], \f[CR]\-\-is\f[R], \f[CR]\-\-all\f[R], or \f[CR]\-\-register=ACCT\f[R]).-.SS Menu+.SS 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 show anything until you have configured account types.-.SS Cash accounts+.SS Cash accounts screen This screen shows \[dq]cash\[dq] (ie, liquid asset) accounts (like \f[CR]hledger balancesheet type:c\f[R]). It always shows balances (historical ending balances on the date shown in the title line).-.SS Balance sheet accounts+.SS Balance sheet accounts screen This screen shows asset, liability and equity accounts (like \f[CR]hledger balancesheetequity\f[R]). It always shows balances.-.SS Income statement accounts+.SS Income statement accounts screen This screen shows revenue and expense accounts (like \f[CR]hledger incomestatement\f[R]). It always shows changes (balance changes in the period shown in the title line).-.SS All accounts+.SS All accounts screen This screen shows all accounts in your journal (unless filtered by a query; like \f[CR]hledger balance\f[R]). It shows balances by default; you can toggle showing changes with the \f[CR]H\f[R] key.-.SS Register+.SS Register screen This screen shows the transactions affecting a particular account. Each line represents one transaction, and shows: .IP \[bu] 2@@ -454,7 +366,7 @@ unlike command\-line hledger). .PP Press \f[CR]RIGHT\f[R] to view the selected transaction in detail.-.SS Transaction+.SS Transaction screen This screen shows a single transaction, as a general journal entry, similar to hledger\[aq]s print command and journal format (hledger_journal(5)).@@ -485,14 +397,13 @@ editor, returning to hledger\-ui \- press \f[CR]g\f[R] to reload the file (or use \f[CR]\-w/\-\-watch\f[R] mode) \- press \f[CR]LEFT\f[R] then \f[CR]RIGHT\f[R] to exit and re\-enter the transaction screen.-.SS Error+.SS 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 again to reload and resume normal operation. (Or, you can press escape to cancel the reload attempt.)-.SH TIPS-.SS Watch mode+.SH WATCH MODE One of hledger\-ui\[aq]s best features is the auto\-reloading \f[CR]\-w/\-\-watch\f[R] mode. With this flag, it will update the display automatically whenever@@ -532,12 +443,6 @@ .PP If you are viewing files mounted from another machine, the system clocks on both machines should be roughly in agreement.-.SS Debug output-You can add \f[CR]\-\-debug[=N]\f[R] to the command line to log debug-output.-This will be logged to the file \f[CR]hledger\-ui.log\f[R] in the-current directory.-N ranges from 1 (least output, the default) to 9 (maximum output). .SH ENVIRONMENT \f[B]COLUMNS\f[R] The screen width to use. Default: the full terminal width.

@@ -11,12 +11,14 @@ hledger-ui(1) ************* -hledger-ui - robust, friendly plain text accounting (TUI version)+hledger-ui - terminal interface (TUI) for 'hledger', a robust, friendly+plain text accounting app.     'hledger-ui [OPTS] [QUERYARGS]'+or 'hledger ui -- [OPTS] [QUERYARGS]' -   This manual is for hledger's terminal interface, version 1.33.1.  See+   This manual is for hledger's terminal interface, version 1.34.  See also the hledger manual for common concepts and file formats.     hledger is a robust, user-friendly, cross-platform set of programs@@ -48,7 +50,7 @@ * MOUSE:: * KEYS:: * SCREENS::-* TIPS::+* WATCH MODE:: * ENVIRONMENT:: * BUGS:: @@ -58,228 +60,106 @@ 1 OPTIONS ********* -Any QUERYARGS are interpreted as a hledger search query which filters-the data.--   hledger-ui provides the following options:--'-w --watch'--     watch for data and date changes and reload automatically-'--theme=default|terminal|greenterm|dark'--     use this custom display theme-'--menu'--     start in the menu screen-'--cash'--     start in the cash accounts screen-'--bs'--     start in the balance sheet accounts screen-'--is'--     start in the income statement accounts screen-'--all'--     start in the all accounts screen-'--register=ACCTREGEX'--     start in the (first) matched account's register screen-'--change'--     show period balances (changes) at startup instead of historical-     balances-'-l --flat'--     show accounts as a flat list (default)-'-t --tree'--     show accounts as a tree--   hledger-ui also supports many of hledger's general options (and the-hledger manual's command line tips also apply here):--* Menu:--* General help options::-* General input options::-* General reporting options::---File: hledger-ui.info,  Node: General help options,  Next: General input options,  Up: OPTIONS--1.1 General help options-========================--'-h --help'--     show general or COMMAND help-'--man'--     show general or COMMAND user manual with man-'--info'--     show general or COMMAND user manual with info-'--version'--     show general or ADDONCMD version-'--debug[=N]'--     show debug output (levels 1-9, default: 1)---File: hledger-ui.info,  Node: General input options,  Next: General reporting options,  Prev: General help options,  Up: OPTIONS--1.2 General input options-=========================--'-f FILE --file=FILE'--     use a different input file.  For stdin, use - (default:-     '$LEDGER_FILE' or '$HOME/.hledger.journal')-'--rules-file=RULESFILE'--     Conversion rules file to use when reading CSV (default: FILE.rules)-'--separator=CHAR'--     Field separator to expect when reading CSV (default: ',')-'--alias=OLD=NEW'--     rename accounts named OLD to NEW-'--pivot FIELDNAME'--     use some other field or tag for the account name-'-I --ignore-assertions'--     disable balance assertion checks (note: does not disable balance-     assignments)-'-s --strict'--     do extra error checking (check that all posted accounts are-     declared)---File: hledger-ui.info,  Node: General reporting options,  Prev: General input options,  Up: OPTIONS--1.3 General reporting options-=============================--'-b --begin=DATE'--     include postings/txns on or after this date (will be adjusted to-     preceding subperiod start when using a report interval)-'-e --end=DATE'--     include postings/txns before this date (will be adjusted to-     following subperiod end when using a report interval)-'-D --daily'--     multiperiod/multicolumn report by day-'-W --weekly'--     multiperiod/multicolumn report by week-'-M --monthly'--     multiperiod/multicolumn report by month-'-Q --quarterly'--     multiperiod/multicolumn report by quarter-'-Y --yearly'--     multiperiod/multicolumn report by year-'-p --period=PERIODEXP'--     set start date, end date, and/or reporting interval all at once-     using period expressions syntax-'--date2'--     match the secondary date instead (see command help for other-     effects)-'--today=DATE'--     override today's date (affects relative smart dates, for-     tests/examples)-'-U --unmarked'--     include only unmarked postings/txns (can combine with -P or -C)-'-P --pending'--     include only pending postings/txns-'-C --cleared'--     include only cleared postings/txns-'-R --real'--     include only non-virtual postings-'-NUM --depth=NUM'--     hide/aggregate accounts or postings more than NUM levels deep-'-E --empty'--     show items with zero amount, normally hidden (and vice-versa in-     hledger-ui/hledger-web)-'-B --cost'--     convert amounts to their cost/selling amount at transaction time-'-V --market'--     convert amounts to their market value in default valuation-     commodities-'-X --exchange=COMM'--     convert amounts to their market value in commodity COMM-'--value'--     convert amounts to cost or market value, more flexibly than-     -B/-V/-X-'--infer-equity'--     infer conversion equity postings from costs-'--infer-costs'--     infer costs from conversion equity postings-'--infer-market-prices'--     use costs as additional market prices, as if they were P directives-'--forecast'--     generate transactions from periodic rules, between the latest-     recorded txn and 6 months from today, or during the specified-     PERIOD (= is required).  Auto posting rules will be applied to-     these transactions as well.  Also, in hledger-ui make future-dated-     transactions visible.-'--auto'--     generate extra postings by applying auto posting rules to all txns-     (not just forecast txns)-'--verbose-tags'+Any arguments are interpreted as a hledger query which filters the data.+hledger-ui provides the following options: -     add visible tags indicating transactions or postings which have-     been generated/modified-'--commodity-style'+Flags:+  -w --watch                watch for data and date changes and reload+                            automatically+     --theme=THEME          use this custom display theme (default,+                            greenterm, terminal, dark)+     --cash                 start in the cash accounts screen+     --bs                   start in the balance sheet accounts screen+     --is                   start in the income statement accounts screen+     --all                  start in the all accounts screen+     --register=ACCTREGEX   start in the (first matched) account's register+     --change               show period balances (changes) at startup instead+                            of historical balances+  -l --flat                 show accounts as a flat list (default)+  -t --tree                 show accounts as a tree -     Override the commodity style in the output for the specified-     commodity.  For example 'EUR1.000,00'.-'--color=WHEN (or --colour=WHEN)'+   and also supports many of hledger's general options: -     Should color-supporting commands use ANSI color codes in text-     output.  'auto' (default): whenever stdout seems to be a-     color-supporting terminal.  'always' or 'yes': always, useful eg-     when piping output into 'less -R'. 'never' or 'no': never.  A-     NO_COLOR environment variable overrides this.-'--pretty[=WHEN]'+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 -     Show prettier output, e.g.  using unicode box-drawing characters.-     Accepts 'yes' (the default) or 'no' ('y', 'n', 'always', 'never'-     also work).  If you provide an argument you must use '=', e.g.-     '-pretty=yes'.+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) -   When a reporting option appears more than once in the command line,-the last one takes precedence.+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 -   Some reporting options can also be written as query arguments.+   With hledger-ui, the '--debug' option sends debug output to a+'hledger-ui.log' file in the current directory.   File: hledger-ui.info,  Node: MOUSE,  Next: KEYS,  Prev: OPTIONS,  Up: Top@@ -399,7 +279,7 @@    Additional screen-specific keys are described below.  -File: hledger-ui.info,  Node: SCREENS,  Next: TIPS,  Prev: KEYS,  Up: Top+File: hledger-ui.info,  Node: SCREENS,  Next: WATCH MODE,  Prev: KEYS,  Up: Top  4 SCREENS *********@@ -415,69 +295,69 @@  * Menu: -* Menu::-* Cash accounts::-* Balance sheet accounts::-* Income statement accounts::-* All accounts::-* Register::-* Transaction::-* Error::+* Menu screen::+* Cash accounts screen::+* Balance sheet accounts screen::+* Income statement accounts screen::+* All accounts screen::+* Register screen::+* Transaction screen::+* Error screen::  -File: hledger-ui.info,  Node: Menu,  Next: Cash accounts,  Up: SCREENS+File: hledger-ui.info,  Node: Menu screen,  Next: Cash accounts screen,  Up: SCREENS -4.1 Menu-========+4.1 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 show anything until you have configured account types.  -File: hledger-ui.info,  Node: Cash accounts,  Next: Balance sheet accounts,  Prev: Menu,  Up: SCREENS+File: hledger-ui.info,  Node: Cash accounts screen,  Next: Balance sheet accounts screen,  Prev: Menu screen,  Up: SCREENS -4.2 Cash accounts-=================+4.2 Cash accounts screen+========================  This screen shows "cash" (ie, liquid asset) accounts (like 'hledger balancesheet type:c').  It always shows balances (historical ending balances on the date shown in the title line).  -File: hledger-ui.info,  Node: Balance sheet accounts,  Next: Income statement accounts,  Prev: Cash accounts,  Up: SCREENS+File: hledger-ui.info,  Node: Balance sheet accounts screen,  Next: Income statement accounts screen,  Prev: Cash accounts screen,  Up: SCREENS -4.3 Balance sheet accounts-==========================+4.3 Balance sheet accounts screen+=================================  This screen shows asset, liability and equity accounts (like 'hledger balancesheetequity').  It always shows balances.  -File: hledger-ui.info,  Node: Income statement accounts,  Next: All accounts,  Prev: Balance sheet accounts,  Up: SCREENS+File: hledger-ui.info,  Node: Income statement accounts screen,  Next: All accounts screen,  Prev: Balance sheet accounts screen,  Up: SCREENS -4.4 Income statement accounts-=============================+4.4 Income statement accounts screen+====================================  This screen shows revenue and expense accounts (like 'hledger incomestatement').  It always shows changes (balance changes in the period shown in the title line).  -File: hledger-ui.info,  Node: All accounts,  Next: Register,  Prev: Income statement accounts,  Up: SCREENS+File: hledger-ui.info,  Node: All accounts screen,  Next: Register screen,  Prev: Income statement accounts screen,  Up: SCREENS -4.5 All accounts-================+4.5 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 toggle showing changes with the 'H' key.  -File: hledger-ui.info,  Node: Register,  Next: Transaction,  Prev: All accounts,  Up: SCREENS+File: hledger-ui.info,  Node: Register screen,  Next: Transaction screen,  Prev: All accounts screen,  Up: SCREENS -4.6 Register-============+4.6 Register screen+===================  This screen shows the transactions affecting a particular account.  Each line represents one transaction, and shows:@@ -529,10 +409,10 @@    Press 'RIGHT' to view the selected transaction in detail.  -File: hledger-ui.info,  Node: Transaction,  Next: Error,  Prev: Register,  Up: SCREENS+File: hledger-ui.info,  Node: Transaction screen,  Next: Error screen,  Prev: Register screen,  Up: SCREENS -4.7 Transaction-===============+4.7 Transaction screen+======================  This screen shows a single transaction, as a general journal entry, similar to hledger's print command and journal format@@ -564,10 +444,10 @@ to exit and re-enter the transaction screen.  -File: hledger-ui.info,  Node: Error,  Prev: Transaction,  Up: SCREENS+File: hledger-ui.info,  Node: Error screen,  Prev: Transaction screen,  Up: SCREENS -4.8 Error-=========+4.8 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@@ -575,21 +455,10 @@ to cancel the reload attempt.)  -File: hledger-ui.info,  Node: TIPS,  Next: ENVIRONMENT,  Prev: SCREENS,  Up: Top--5 TIPS-******--* Menu:--* Watch mode::-* Debug output::---File: hledger-ui.info,  Node: Watch mode,  Next: Debug output,  Up: TIPS+File: hledger-ui.info,  Node: WATCH MODE,  Next: ENVIRONMENT,  Prev: SCREENS,  Up: Top -5.1 Watch mode-==============+5 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 whenever@@ -626,17 +495,7 @@ clocks on both machines should be roughly in agreement.  -File: hledger-ui.info,  Node: Debug output,  Prev: Watch mode,  Up: TIPS--5.2 Debug output-================--You can add '--debug[=N]' to the command line to log debug output.  This-will be logged to the file 'hledger-ui.log' in the current directory.  N-ranges from 1 (least output, the default) to 9 (maximum output).---File: hledger-ui.info,  Node: ENVIRONMENT,  Next: BUGS,  Prev: TIPS,  Up: Top+File: hledger-ui.info,  Node: ENVIRONMENT,  Next: BUGS,  Prev: WATCH MODE,  Up: Top  6 ENVIRONMENT *************@@ -671,46 +530,36 @@  Tag Table: Node: Top221-Node: OPTIONS1830-Ref: #options1928-Node: General help options2956-Ref: #general-help-options3105-Node: General input options3387-Ref: #general-input-options3572-Node: General reporting options4229-Ref: #general-reporting-options4393-Node: MOUSE7783-Ref: #mouse7878-Node: KEYS8115-Ref: #keys8208-Node: SCREENS12863-Ref: #screens12961-Node: Menu13541-Ref: #menu13634-Node: Cash accounts13829-Ref: #cash-accounts13971-Node: Balance sheet accounts14155-Ref: #balance-sheet-accounts14336-Node: Income statement accounts14456-Ref: #income-statement-accounts14642-Node: All accounts14806-Ref: #all-accounts14952-Node: Register15134-Ref: #register15258-Node: Transaction17542-Ref: #transaction17665-Node: Error19082-Ref: #error19176-Node: TIPS19420-Ref: #tips19519-Node: Watch mode19561-Ref: #watch-mode19668-Node: Debug output21127-Ref: #debug-output21238-Node: ENVIRONMENT21450-Ref: #environment21560-Node: BUGS21751-Ref: #bugs21834+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  End Tag Table 

@@ -0,0 +1,32 @@+# hledger-ui++> A terminal interface (TUI) for `hledger`, a robust, friendly plain text accounting app.+> More information: <https://hledger.org/hledger-ui.html>.++- Start in the main menu screen, reading from the default journal file:++`hledger-ui`++- Start with a different color theme:++`hledger-ui --theme {{terminal|greenterm|dark}}`++- Start in the balance sheet accounts screen, showing hierarchy down to level 3:++`hledger-ui --bs --tree --depth 3`++- Start in this account's screen, showing cleared transactions, and reload on change:++`hledger-ui --register {{assets:bank:checking}} --cleared --watch`++- Read two journal files, and show amounts as current value when known:++`hledger-ui --file {{path/to/2024.journal}} --file {{path/to/2024-prices.journal}} --value now`++- Show the manual in Info format, if possible:++`hledger-ui --info`++- Display help:++`hledger-ui --help`

@@ -2,231 +2,142 @@ HLEDGER-UI(1)                hledger User Manuals                HLEDGER-UI(1)  NAME-       hledger-ui - robust, friendly plain text accounting (TUI version)+       hledger-ui  -  terminal interface (TUI) for hledger, a robust, friendly+       plain text accounting app.  SYNOPSIS        hledger-ui    [OPTS] [QUERYARGS]+       or        hledger ui -- [OPTS] [QUERYARGS]  DESCRIPTION-       This  manual  is for hledger's terminal interface, version 1.33.1.  See+       This manual is for hledger's terminal  interface,  version  1.34.   See        also the hledger manual for common concepts and file formats. -       hledger is a robust, user-friendly, cross-platform set of programs  for-       tracking  money,  time,  or any other commodity, using double-entry ac--       counting and a simple, editable file format.  hledger  is  inspired  by-       and  largely  compatible  with  ledger(1), and largely interconvertible+       hledger  is a robust, user-friendly, cross-platform set of programs for+       tracking money, time, or any other commodity,  using  double-entry  ac-+       counting  and  a  simple, editable file format.  hledger is inspired by+       and largely compatible with  ledger(1),  and  largely  interconvertible        with beancount(1). -       hledger-ui is hledger's  terminal  interface,  providing  an  efficient-       full-window  text  UI  for  viewing accounts and transactions, and some-       limited data entry  capability.   It  is  easier  than  hledger's  com-+       hledger-ui  is  hledger's  terminal  interface,  providing an efficient+       full-window text UI for viewing accounts  and  transactions,  and  some+       limited  data  entry  capability.   It  is  easier  than hledger's com-        mand-line interface, and sometimes quicker and more convenient than the        web interface. -       Like  hledger,  it reads from (and appends to) a journal file specified-       by   the    LEDGER_FILE    environment    variable    (defaulting    to-       $HOME/.hledger.journal);  or you can specify files with -f options.  It-       can also read timeclock files, timedot files, or any  CSV/SSV/TSV  file+       Like hledger, it reads from (and appends to) a journal  file  specified+       by    the    LEDGER_FILE    environment    variable    (defaulting   to+       $HOME/.hledger.journal); or you can specify files with -f options.   It+       can  also  read timeclock files, timedot files, or any CSV/SSV/TSV file        with a date field.  (See hledger(1) -> Input for details.) -       Unlike  hledger,  hledger-ui hides all future-dated transactions by de--       fault.  They can be revealed, along with  any  rule-generated  periodic-       transactions,  by  pressing  the F key (or starting with --forecast) to+       Unlike hledger, hledger-ui hides all future-dated transactions  by  de-+       fault.   They  can  be revealed, along with any rule-generated periodic+       transactions, by pressing the F key (or starting  with  --forecast)  to        enable "forecast mode".  OPTIONS-       Any QUERYARGS are interpreted as a hledger search query  which  filters-       the data.--       hledger-ui provides the following options:--       -w --watch-              watch for data and date changes and reload automatically--       --theme=default|terminal|greenterm|dark-              use this custom display theme--       --menu start in the menu screen--       --cash start in the cash accounts screen--       --bs   start in the balance sheet accounts screen--       --is   start in the income statement accounts screen--       --all  start in the all accounts screen--       --register=ACCTREGEX-              start in the (first) matched account's register screen--       --change-              show  period balances (changes) at startup instead of historical-              balances--       -l --flat-              show accounts as a flat list (default)--       -t --tree-              show accounts as a tree--       hledger-ui also supports many of hledger's  general  options  (and  the-       hledger manual's command line tips also apply here):--   General help options-       -h --help-              show general or COMMAND help--       --man  show general or COMMAND user manual with man--       --info show general or COMMAND user manual with info--       --version-              show general or ADDONCMD version--       --debug[=N]-              show debug output (levels 1-9, default: 1)--   General input options-       -f FILE --file=FILE-              use  a  different  input  file.   For  stdin,  use  -  (default:-              $LEDGER_FILE or $HOME/.hledger.journal)--       --rules-file=RULESFILE-              Conversion  rules  file  to  use  when  reading  CSV   (default:-              FILE.rules)--       --separator=CHAR-              Field separator to expect when reading CSV (default: ',')--       --alias=OLD=NEW-              rename accounts named OLD to NEW--       --pivot FIELDNAME-              use some other field or tag for the account name--       -I --ignore-assertions-              disable balance assertion checks (note: does not disable balance-              assignments)--       -s --strict-              do  extra error checking (check that all posted accounts are de--              clared)--   General reporting options-       -b --begin=DATE-              include postings/txns on or after this date (will be adjusted to-              preceding subperiod start when using a report interval)--       -e --end=DATE-              include postings/txns before this date (will be adjusted to fol--              lowing subperiod end when using a report interval)--       -D --daily-              multiperiod/multicolumn report by day--       -W --weekly-              multiperiod/multicolumn report by week--       -M --monthly-              multiperiod/multicolumn report by month--       -Q --quarterly-              multiperiod/multicolumn report by quarter--       -Y --yearly-              multiperiod/multicolumn report by year--       -p --period=PERIODEXP-              set start date, end date, and/or reporting interval all at  once-              using period expressions syntax--       --date2-              match the secondary date instead (see command help for other ef--              fects)--       --today=DATE-              override   today's  date  (affects  relative  smart  dates,  for-              tests/examples)--       -U --unmarked-              include only unmarked postings/txns (can combine with -P or -C)--       -P --pending-              include only pending postings/txns--       -C --cleared-              include only cleared postings/txns--       -R --real-              include only non-virtual postings--       -NUM --depth=NUM-              hide/aggregate accounts or postings more than NUM levels deep--       -E --empty-              show items with zero amount, normally hidden (and vice-versa  in-              hledger-ui/hledger-web)--       -B --cost-              convert amounts to their cost/selling amount at transaction time--       -V --market-              convert  amounts to their market value in default valuation com--              modities--       -X --exchange=COMM-              convert amounts to their market value in commodity COMM--       --value-              convert amounts to cost or  market  value,  more  flexibly  than-              -B/-V/-X--       --infer-equity-              infer conversion equity postings from costs--       --infer-costs-              infer costs from conversion equity postings--       --infer-market-prices-              use  costs as additional market prices, as if they were P direc--              tives--       --forecast-              generate transactions from periodic rules,  between  the  latest-              recorded  txn  and  6 months from today, or during the specified-              PERIOD (= is required).  Auto posting rules will be  applied  to-              these  transactions  as  well.   Also,  in  hledger-ui  make fu--              ture-dated transactions visible.--       --auto generate extra postings by applying auto posting  rules  to  all-              txns (not just forecast txns)+       Any  arguments  are  interpreted  as  a hledger query which filters the+       data.  hledger-ui provides the following options: -       --verbose-tags-              add  visible tags indicating transactions or postings which have-              been generated/modified+              Flags:+                -w --watch                watch for data and date changes and reload+                                          automatically+                   --theme=THEME          use this custom display theme (default,+                                          greenterm, terminal, dark)+                   --cash                 start in the cash accounts screen+                   --bs                   start in the balance sheet accounts screen+                   --is                   start in the income statement accounts screen+                   --all                  start in the all accounts screen+                   --register=ACCTREGEX   start in the (first matched) account's register+                   --change               show period balances (changes) at startup instead+                                          of historical balances+                -l --flat                 show accounts as a flat list (default)+                -t --tree                 show accounts as a tree -       --commodity-style-              Override the commodity style in the  output  for  the  specified-              commodity.  For example 'EUR1.000,00'.+       and also supports many of hledger's general options: -       --color=WHEN (or --colour=WHEN)-              Should  color-supporting  commands  use ANSI color codes in text-              output.   'auto'  (default):  whenever  stdout  seems  to  be  a-              color-supporting terminal.  'always' or 'yes': always, useful eg-              when  piping  output into 'less -R'.  'never' or 'no': never.  A-              NO_COLOR environment variable overrides this.+              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 -       --pretty[=WHEN]-              Show prettier output, e.g.  using  unicode  box-drawing  charac--              ters.   Accepts 'yes' (the default) or 'no' ('y', 'n', 'always',-              'never' also work).  If you provide an  argument  you  must  use-              '=', e.g.  '--pretty=yes'.+              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) -       When a reporting option appears more than once in the command line, the-       last one takes precedence.+              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 -       Some reporting options can also be written as query arguments.+       With  hledger-ui,  the  --debug  option  sends  debug   output   to   a+       hledger-ui.log file in the current directory.  MOUSE        In  most  modern terminals, you can navigate through the screens with a@@ -345,31 +256,31 @@        You can also use a command line flag to specific  a  different  startup        screen (--cs, --bs, --is, --all, or --register=ACCT). -   Menu+   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        show anything until you have configured account types. -   Cash accounts+   Cash accounts screen        This screen shows "cash" (ie, liquid asset) accounts (like hledger bal-        ancesheet  type:c).   It  always shows balances (historical ending bal-        ances on the date shown in the title line). -   Balance sheet accounts+   Balance sheet accounts screen        This screen shows asset, liability and equity  accounts  (like  hledger        balancesheetequity).  It always shows balances. -   Income statement accounts+   Income statement accounts screen        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+   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        toggle showing changes with the H key. -   Register+   Register screen        This  screen  shows  the  transactions  affecting a particular account.        Each line represents one transaction, and shows: @@ -418,7 +329,7 @@         Press RIGHT to view the selected transaction in detail. -   Transaction+   Transaction screen        This screen shows a single transaction, as  a  general  journal  entry,        similar  to  hledger's  print command and journal format (hledger_jour-        nal(5)).@@ -447,14 +358,13 @@        file  (or  use  -w/--watch  mode)  -  press LEFT then RIGHT to exit and        re-enter the transaction screen. -   Error+   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        again to reload and resume normal operation.  (Or, you can press escape        to cancel the reload attempt.) -TIPS-   Watch mode+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-        ever changes are saved to the data files.@@ -489,11 +399,6 @@        If you are viewing files  mounted  from  another  machine,  the  system        clocks on both machines should be roughly in agreement. -   Debug output-       You  can add --debug[=N] to the command line to log debug output.  This-       will be logged to the file hledger-ui.log in the current directory.   N-       ranges from 1 (least output, the default) to 9 (maximum output).- ENVIRONMENT        COLUMNS The screen width to use.  Default: the full terminal width. @@ -535,4 +440,4 @@ SEE ALSO        hledger(1), hledger-ui(1), hledger-web(1), ledger(1) -hledger-ui-1.33.1                  May 2024                      HLEDGER-UI(1)+hledger-ui-1.34                    June 2024                     HLEDGER-UI(1)

@@ -1,18 +1,23 @@ -.TH "HLEDGER\-WEB" "1" "May 2024" "hledger-web-1.33.1 " "hledger User Manuals"+.TH "HLEDGER\-WEB" "1" "June 2024" "hledger-web-1.34 " "hledger User Manuals"    .SH NAME-hledger\-web \- robust, friendly plain text accounting (Web version)+hledger\-web \- web interface and API for \f[CR]hledger\f[R], a robust,+friendly plain text accounting app. .SH SYNOPSIS-\f[CR]hledger\-web    [\-\-serve|\-\-serve\-api] [OPTS] [ARGS]\f[R]+\f[CR]hledger\-web    [OPTS] [QUERY]\f[R] .PD 0 .P .PD-\f[CR]hledger web \-\- [\-\-serve|\-\-serve\-api] [OPTS] [ARGS]\f[R]+or+.PD 0+.P+.PD+\f[CR]hledger web \-\- [OPTS] [QUERY]\f[R] .SH DESCRIPTION-This manual is for hledger\[aq]s web interface, version 1.33.1.+This manual is for hledger\[aq]s web interface, version 1.34. See also the hledger manual for common concepts and file formats. .PP hledger is a robust, user\-friendly, cross\-platform set of programs for@@ -60,45 +65,41 @@ to stdout. .SH OPTIONS hledger\-web provides the following options:-.TP-\f[CR]\-\-serve\f[R]-serve and log requests, don\[aq]t browse or auto\-exit after timeout-.TP-\f[CR]\-\-serve\-api\f[R]-like \-\-serve, but serve only the JSON web API, not the web UI-.TP-\f[CR]\-\-allow=view|add|edit\f[R]-set the user\[aq]s access level for changing data (default:-\f[CR]add\f[R]).-It also accepts \f[CR]sandstorm\f[R] for use on that platform (reads-permissions from the \f[CR]X\-Sandstorm\-Permissions\f[R] request-header).-.TP-\f[CR]\-\-cors=ORIGIN\f[R]-allow cross\-origin requests from the specified origin; setting ORIGIN-to \[dq]*\[dq] allows requests from any origin-.TP-\f[CR]\-\-host=IPADDR\f[R]-listen on this IP address (default: 127.0.0.1)+.IP+.EX+Flags:+     \-\-serve \-\-server       serve and log requests, don\[aq]t browse or auto\-exit+     \-\-serve\-api            like \-\-serve, but serve only the JSON web API,+                            not the web UI+     \-\-allow=view|add|edit  set the user\[aq]s access level for changing data+                            (default: \[ga]add\[ga]). It also accepts \[ga]sandstorm\[ga] for+                            use on that platform (reads permissions from the+                            \[ga]X\-Sandstorm\-Permissions\[ga] request header).+     \-\-cors=ORIGIN          allow cross\-origin requests from the specified+                            origin; setting ORIGIN to \[dq]*\[dq] allows requests from+                            any origin+     \-\-host=IPADDR          listen on this IP address (default: 127.0.0.1)+     \-\-port=PORT            listen on this TCP port (default: 5000)+     \-\-socket=SOCKET        listen on the given unix socket instead of an IP+                            address and port (unix only; implies \-\-serve)+     \-\-base\-url=BASEURL     set the base url (default: http://IPADDR:PORT)+     \-\-test                 run hledger\-web\[aq]s tests and exit. hspec test+                            runner args may follow a \-\-, eg: hledger\-web \-\-test+                            \-\- \-\-help+.EE .PP-By default the server listens on IP address \f[CR]127.0.0.1\f[R], which-is accessible only to requests from the local machine..-You can use \f[CR]\-\-host\f[R] to listen on a different address-configured on the machine, eg to allow access from other machines.-The special address \f[CR]0.0.0.0\f[R] causes it to listen on all-addresses configured on the machine.-.TP-\f[CR]\-\-port=PORT\f[R]-listen on this TCP port (default: 5000)+By default hledger\-web listens only on IP address \f[CR]127.0.0.1\f[R],+which be accessed only from the local machine. .PP+To allow access from elsewhere, use \f[CR]\-\-host\f[R] to specify an+externally accessible address configured on this machine, The special+address \f[CR]0.0.0.0\f[R] causes it to listen on all of this+machine\[aq]s addresses.+.PP Similarly, you can use \f[CR]\-\-port\f[R] to listen on a TCP port other than 5000. This is useful if you want to run multiple hledger\-web instances on a machine.-.TP-\f[CR]\-\-socket=SOCKETFILE\f[R]-listen on the given unix socket instead of an IP address and port (unix-only; implies \-\-serve) .PP When \f[CR]\-\-socket\f[R] is used, hledger\-web creates and communicates via a socket file instead of a TCP port.@@ -107,9 +108,6 @@ nginx reverse proxy. (Eg: \f[CR]proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;\f[R].)-.TP-\f[CR]\-\-base\-url=URL\f[R]-set the base url (default: http://IPADDR:PORT). .PP You can use \f[CR]\-\-base\-url\f[R] to change the protocol, hostname, port and path that appear in hledger\-web\[aq]s hyperlinks.@@ -118,182 +116,100 @@ configured host address and TCP port (or \f[CR]http://HOST\f[R] if PORT is 80). Note this affects url generation but not route parsing.-.TP-\f[CR]\-\-test\f[R]-run hledger\-web\[aq]s tests and exit.-hspec test runner args may follow a \-\-, eg: hledger\-web \-\-test \-\--\-\-help .PP-hledger\-web also supports many of hledger\[aq]s general options.-Query options and arguments may be used to set an initial filter, which-although not shown in the UI, will restrict the data shown, in addition-to any search query entered in the UI.-.PP-Note that hledger\-web shows accounts with zero balances by default,-like \f[CR]hledger\-ui\f[R] (and unlike \f[CR]hledger\f[R]).-Using the \f[CR]\-E/\-\-empty\f[R] flag at startup will hide them.+hledger\-web also supports many of hledger\[aq]s general options:+.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+                            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 (\[dq]=\[dq]) to all transactions+     \-\-forecast[=PERIOD]    Generate extra transactions from periodic rules+                            (\[dq]\[ti]\[dq]), 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\[aq]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\[aq]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:+                            \[aq]then\[aq]:     value on transaction dates+                            \[aq]end\[aq]:      value at period end(s)+                            \[aq]now\[aq]:      value today+                            YYYY\-MM\-DD: value on given date+  \-c \-\-commodity\-style=S    Override a commodity\[aq]s display style.+                            Eg: \-c \[aq].\[aq] or \-c \[aq]1.000,00 EUR\[aq]+     \-\-color=YN \-\-colour    Use ANSI color codes in text output? Can be+                            \[aq]y\[aq]/\[aq]yes\[aq]/\[aq]always\[aq], \[aq]n\[aq]/\[aq]no\[aq]/\[aq]never\[aq] or \[aq]auto\[aq].+     \-\-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+     \-\-tldr                 show command examples with tldr+     \-\-info                 show the manual with info+     \-\-man                  show the manual with man+     \-\-version              show version information+.EE .PP+hledger\-web shows accounts with zero balances by default (like+\f[CR]hledger\-ui\f[R], and unlike \f[CR]hledger\f[R]).+Using the \f[CR]\-E/\-\-empty\f[R] flag will reverse this behaviour. If you see accounts which appear to have a zero balance, but cannot be-hidden with \f[CR]\-E\f[R]: these have a mixed\-cost balance which looks-like zero when costs are hidden.-Currently hledger\-web does not show costs at all.-.SS General help options-.TP-\f[CR]\-h \-\-help\f[R]-show general or COMMAND help-.TP-\f[CR]\-\-man\f[R]-show general or COMMAND user manual with man-.TP-\f[CR]\-\-info\f[R]-show general or COMMAND user manual with info-.TP-\f[CR]\-\-version\f[R]-show general or ADDONCMD version-.TP-\f[CR]\-\-debug[=N]\f[R]-show debug output (levels 1\-9, default: 1)-.SS General input options-.TP-\f[CR]\-f FILE \-\-file=FILE\f[R]-use a different input file.-For stdin, use \- (default: \f[CR]$LEDGER_FILE\f[R] or-\f[CR]$HOME/.hledger.journal\f[R])-.TP-\f[CR]\-\-rules\-file=RULESFILE\f[R]-Conversion rules file to use when reading CSV (default: FILE.rules)-.TP-\f[CR]\-\-separator=CHAR\f[R]-Field separator to expect when reading CSV (default: \[aq],\[aq])-.TP-\f[CR]\-\-alias=OLD=NEW\f[R]-rename accounts named OLD to NEW-.TP-\f[CR]\-\-pivot FIELDNAME\f[R]-use some other field or tag for the account name-.TP-\f[CR]\-I \-\-ignore\-assertions\f[R]-disable balance assertion checks (note: does not disable balance-assignments)-.TP-\f[CR]\-s \-\-strict\f[R]-do extra error checking (check that all posted accounts are declared)-.SS General reporting options-.TP-\f[CR]\-b \-\-begin=DATE\f[R]-include postings/txns on or after this date (will be adjusted to-preceding subperiod start when using a report interval)-.TP-\f[CR]\-e \-\-end=DATE\f[R]-include postings/txns before this date (will be adjusted to following-subperiod end when using a report interval)-.TP-\f[CR]\-D \-\-daily\f[R]-multiperiod/multicolumn report by day-.TP-\f[CR]\-W \-\-weekly\f[R]-multiperiod/multicolumn report by week-.TP-\f[CR]\-M \-\-monthly\f[R]-multiperiod/multicolumn report by month-.TP-\f[CR]\-Q \-\-quarterly\f[R]-multiperiod/multicolumn report by quarter-.TP-\f[CR]\-Y \-\-yearly\f[R]-multiperiod/multicolumn report by year-.TP-\f[CR]\-p \-\-period=PERIODEXP\f[R]-set start date, end date, and/or reporting interval all at once using-period expressions syntax-.TP-\f[CR]\-\-date2\f[R]-match the secondary date instead (see command help for other effects)-.TP-\f[CR]\-\-today=DATE\f[R]-override today\[aq]s date (affects relative smart dates, for-tests/examples)-.TP-\f[CR]\-U \-\-unmarked\f[R]-include only unmarked postings/txns (can combine with \-P or \-C)-.TP-\f[CR]\-P \-\-pending\f[R]-include only pending postings/txns-.TP-\f[CR]\-C \-\-cleared\f[R]-include only cleared postings/txns-.TP-\f[CR]\-R \-\-real\f[R]-include only non\-virtual postings-.TP-\f[CR]\-NUM \-\-depth=NUM\f[R]-hide/aggregate accounts or postings more than NUM levels deep-.TP-\f[CR]\-E \-\-empty\f[R]-show items with zero amount, normally hidden (and vice\-versa in-hledger\-ui/hledger\-web)-.TP-\f[CR]\-B \-\-cost\f[R]-convert amounts to their cost/selling amount at transaction time-.TP-\f[CR]\-V \-\-market\f[R]-convert amounts to their market value in default valuation commodities-.TP-\f[CR]\-X \-\-exchange=COMM\f[R]-convert amounts to their market value in commodity COMM-.TP-\f[CR]\-\-value\f[R]-convert amounts to cost or market value, more flexibly than \-B/\-V/\-X-.TP-\f[CR]\-\-infer\-equity\f[R]-infer conversion equity postings from costs-.TP-\f[CR]\-\-infer\-costs\f[R]-infer costs from conversion equity postings-.TP-\f[CR]\-\-infer\-market\-prices\f[R]-use costs as additional market prices, as if they were P directives-.TP-\f[CR]\-\-forecast\f[R]-generate transactions from periodic rules,-between the latest recorded txn and 6 months from today,-or during the specified PERIOD (= is required).-Auto posting rules will be applied to these transactions as well.-Also, in hledger\-ui make future\-dated transactions visible.-.TP-\f[CR]\-\-auto\f[R]-generate extra postings by applying auto posting rules to all txns (not-just forecast txns)-.TP-\f[CR]\-\-verbose\-tags\f[R]-add visible tags indicating transactions or postings which have been-generated/modified-.TP-\f[CR]\-\-commodity\-style\f[R]-Override the commodity style in the output for the specified commodity.-For example \[aq]EUR1.000,00\[aq].-.TP-\f[CR]\-\-color=WHEN (or \-\-colour=WHEN)\f[R]-Should color\-supporting commands use ANSI color codes in text output.-\[aq]auto\[aq] (default): whenever stdout seems to be a-color\-supporting terminal.-\[aq]always\[aq] or \[aq]yes\[aq]: always, useful eg when piping output-into \[aq]less \-R\[aq].-\[aq]never\[aq] or \[aq]no\[aq]: never.-A NO_COLOR environment variable overrides this.-.TP-\f[CR]\-\-pretty[=WHEN]\f[R]-Show prettier output, e.g.-using unicode box\-drawing characters.-Accepts \[aq]yes\[aq] (the default) or \[aq]no\[aq] (\[aq]y\[aq],-\[aq]n\[aq], \[aq]always\[aq], \[aq]never\[aq] also work).-If you provide an argument you must use \[aq]=\[aq], e.g.-\[aq]\-\-pretty=yes\[aq].-.PP-When a reporting option appears more than once in the command line, the-last one takes precedence.+hidden with \f[CR]\-E\f[R], it\[aq]s because they have a mixed\-cost+balance, which looks like zero when costs are hidden.+(hledger\-web does not show costs.) .PP-Some reporting options can also be written as query arguments.+Reporting options and/or query arguments can be used to set an initial+query, which although not shown in the UI, will restrict the data shown+(in addition to any search query entered in the UI). .SH PERMISSIONS By default, hledger\-web allows anyone who can reach it to view the journal and to add new transactions, but not to change existing data.@@ -434,6 +350,7 @@ what the fields mean, see the Hledger.Data.Json haddock docs and click on the various data types, eg Transaction. And for a higher level understanding, see the journal docs.+There is also a basic OpenAPI specification. .PP In some cases there is outer JSON corresponding to a \[dq]Report\[dq] type.@@ -468,22 +385,22 @@     \[dq]tcomment\[dq]: \[dq]\[dq],     \[dq]tpostings\[dq]: [         {-            \[dq]pbalanceassertion\[dq]: null,+            \[dq]pbalanceassertion\[dq]: \f[B]null\f[R],             \[dq]pstatus\[dq]: \[dq]Unmarked\[dq],             \[dq]pamount\[dq]: [                 {-                    \[dq]aprice\[dq]: null,+                    \[dq]aprice\[dq]: \f[B]null\f[R],                     \[dq]acommodity\[dq]: \[dq]$\[dq],                     \[dq]aquantity\[dq]: {                         \[dq]floatingPoint\[dq]: 1,                         \[dq]decimalPlaces\[dq]: 10,                         \[dq]decimalMantissa\[dq]: 10000000000                     },-                    \[dq]aismultiplier\[dq]: false,+                    \[dq]aismultiplier\[dq]: \f[B]false\f[R],                     \[dq]astyle\[dq]: {                         \[dq]ascommodityside\[dq]: \[dq]L\[dq],-                        \[dq]asdigitgroups\[dq]: null,-                        \[dq]ascommodityspaced\[dq]: false,+                        \[dq]asdigitgroups\[dq]: \f[B]null\f[R],+                        \[dq]ascommodityspaced\[dq]: \f[B]false\f[R],                         \[dq]asprecision\[dq]: 2,                         \[dq]asdecimalpoint\[dq]: \[dq].\[dq]                     }@@ -491,30 +408,30 @@             ],             \[dq]ptransaction_\[dq]: \[dq]1\[dq],             \[dq]paccount\[dq]: \[dq]assets:bank:checking\[dq],-            \[dq]pdate\[dq]: null,+            \[dq]pdate\[dq]: \f[B]null\f[R],             \[dq]ptype\[dq]: \[dq]RegularPosting\[dq],             \[dq]pcomment\[dq]: \[dq]\[dq],-            \[dq]pdate2\[dq]: null,+            \[dq]pdate2\[dq]: \f[B]null\f[R],             \[dq]ptags\[dq]: [],-            \[dq]poriginal\[dq]: null+            \[dq]poriginal\[dq]: \f[B]null\f[R]         },         {-            \[dq]pbalanceassertion\[dq]: null,+            \[dq]pbalanceassertion\[dq]: \f[B]null\f[R],             \[dq]pstatus\[dq]: \[dq]Unmarked\[dq],             \[dq]pamount\[dq]: [                 {-                    \[dq]aprice\[dq]: null,+                    \[dq]aprice\[dq]: \f[B]null\f[R],                     \[dq]acommodity\[dq]: \[dq]$\[dq],                     \[dq]aquantity\[dq]: {                         \[dq]floatingPoint\[dq]: \-1,                         \[dq]decimalPlaces\[dq]: 10,                         \[dq]decimalMantissa\[dq]: \-10000000000                     },-                    \[dq]aismultiplier\[dq]: false,+                    \[dq]aismultiplier\[dq]: \f[B]false\f[R],                     \[dq]astyle\[dq]: {                         \[dq]ascommodityside\[dq]: \[dq]L\[dq],-                        \[dq]asdigitgroups\[dq]: null,-                        \[dq]ascommodityspaced\[dq]: false,+                        \[dq]asdigitgroups\[dq]: \f[B]null\f[R],+                        \[dq]ascommodityspaced\[dq]: \f[B]false\f[R],                         \[dq]asprecision\[dq]: 2,                         \[dq]asdecimalpoint\[dq]: \[dq].\[dq]                     }@@ -522,12 +439,12 @@             ],             \[dq]ptransaction_\[dq]: \[dq]1\[dq],             \[dq]paccount\[dq]: \[dq]income:salary\[dq],-            \[dq]pdate\[dq]: null,+            \[dq]pdate\[dq]: \f[B]null\f[R],             \[dq]ptype\[dq]: \[dq]RegularPosting\[dq],             \[dq]pcomment\[dq]: \[dq]\[dq],-            \[dq]pdate2\[dq]: null,+            \[dq]pdate2\[dq]: \f[B]null\f[R],             \[dq]ptags\[dq]: [],-            \[dq]poriginal\[dq]: null+            \[dq]poriginal\[dq]: \f[B]null\f[R]         }     ],     \[dq]ttags\[dq]: [],@@ -545,7 +462,7 @@     \[dq]tcode\[dq]: \[dq]\[dq],     \[dq]tindex\[dq]: 1,     \[dq]tprecedingcomment\[dq]: \[dq]\[dq],-    \[dq]tdate2\[dq]: null,+    \[dq]tdate2\[dq]: \f[B]null\f[R],     \[dq]tdescription\[dq]: \[dq]income\[dq],     \[dq]tstatus\[dq]: \[dq]Unmarked\[dq] }

@@ -11,12 +11,14 @@ hledger-web(1) ************** -hledger-web - robust, friendly plain text accounting (Web version)+hledger-web - web interface and API for 'hledger', a robust, friendly+plain text accounting app. -   'hledger-web [--serve|--serve-api] [OPTS] [ARGS]'-'hledger web -- [--serve|--serve-api] [OPTS] [ARGS]'+   'hledger-web [OPTS] [QUERY]'+or+'hledger web -- [OPTS] [QUERY]' -   This manual is for hledger's web interface, version 1.33.1.  See also+   This manual is for hledger's web interface, version 1.34.  See also the hledger manual for common concepts and file formats.     hledger is a robust, user-friendly, cross-platform set of programs@@ -77,54 +79,43 @@  hledger-web provides the following options: -'--serve'--     serve and log requests, don't browse or auto-exit after timeout-'--serve-api'--     like -serve, but serve only the JSON web API, not the web UI-'--allow=view|add|edit'--     set the user's access level for changing data (default: 'add').  It-     also accepts 'sandstorm' for use on that platform (reads-     permissions from the 'X-Sandstorm-Permissions' request header).-'--cors=ORIGIN'--     allow cross-origin requests from the specified origin; setting-     ORIGIN to "*" allows requests from any origin-'--host=IPADDR'--     listen on this IP address (default: 127.0.0.1)--   By default the server listens on IP address '127.0.0.1', which is-accessible only to requests from the local machine..  You can use-'--host' to listen on a different address configured on the machine, eg-to allow access from other machines.  The special address '0.0.0.0'-causes it to listen on all addresses configured on the machine.+Flags:+     --serve --server       serve and log requests, don't browse or auto-exit+     --serve-api            like --serve, but serve only the JSON web API,+                            not the web UI+     --allow=view|add|edit  set the user's access level for changing data+                            (default: `add`). It also accepts `sandstorm` for+                            use on that platform (reads permissions from the+                            `X-Sandstorm-Permissions` request header).+     --cors=ORIGIN          allow cross-origin requests from the specified+                            origin; setting ORIGIN to "*" allows requests from+                            any origin+     --host=IPADDR          listen on this IP address (default: 127.0.0.1)+     --port=PORT            listen on this TCP port (default: 5000)+     --socket=SOCKET        listen on the given unix socket instead of an IP+                            address and port (unix only; implies --serve)+     --base-url=BASEURL     set the base url (default: http://IPADDR:PORT)+     --test                 run hledger-web's tests and exit. hspec test+                            runner args may follow a --, eg: hledger-web --test+                            -- --help -'--port=PORT'+   By default hledger-web listens only on IP address '127.0.0.1', which+be accessed only from the local machine. -     listen on this TCP port (default: 5000)+   To allow access from elsewhere, use '--host' to specify an externally+accessible address configured on this machine, The special address+'0.0.0.0' causes it to listen on all of this machine's addresses.     Similarly, you can use '--port' to listen on a TCP port other than 5000.  This is useful if you want to run multiple hledger-web instances on a machine. -'--socket=SOCKETFILE'--     listen on the given unix socket instead of an IP address and port-     (unix only; implies -serve)-    When '--socket' is used, hledger-web creates and communicates via a socket file instead of a TCP port.  This can be more secure, respects unix file permissions, and makes certain use cases easier, such as running per-user instances behind an nginx reverse proxy.  (Eg: 'proxy_pass http://unix:/tmp/hledger/${remote_user}.socket;'.) -'--base-url=URL'--     set the base url (default: http://IPADDR:PORT).-    You can use '--base-url' to change the protocol, hostname, port and path that appear in hledger-web's hyperlinks.  This is useful eg when integrating hledger-web within a larger website.  The default is@@ -132,204 +123,96 @@ port (or 'http://HOST' if PORT is 80).  Note this affects url generation but not route parsing. -'--test'--     run hledger-web's tests and exit.  hspec test runner args may-     follow a -, eg: hledger-web -test - -help--   hledger-web also supports many of hledger's general options.  Query-options and arguments may be used to set an initial filter, which-although not shown in the UI, will restrict the data shown, in addition-to any search query entered in the UI.--   Note that hledger-web shows accounts with zero balances by default,-like 'hledger-ui' (and unlike 'hledger').  Using the '-E/--empty' flag-at startup will hide them.--   If you see accounts which appear to have a zero balance, but cannot-be hidden with '-E': these have a mixed-cost balance which looks like-zero when costs are hidden.  Currently hledger-web does not show costs-at all.--* Menu:--* General help options::-* General input options::-* General reporting options::---File: hledger-web.info,  Node: General help options,  Next: General input options,  Up: OPTIONS--1.1 General help options-========================--'-h --help'--     show general or COMMAND help-'--man'--     show general or COMMAND user manual with man-'--info'--     show general or COMMAND user manual with info-'--version'--     show general or ADDONCMD version-'--debug[=N]'--     show debug output (levels 1-9, default: 1)---File: hledger-web.info,  Node: General input options,  Next: General reporting options,  Prev: General help options,  Up: OPTIONS--1.2 General input options-=========================--'-f FILE --file=FILE'--     use a different input file.  For stdin, use - (default:-     '$LEDGER_FILE' or '$HOME/.hledger.journal')-'--rules-file=RULESFILE'--     Conversion rules file to use when reading CSV (default: FILE.rules)-'--separator=CHAR'--     Field separator to expect when reading CSV (default: ',')-'--alias=OLD=NEW'--     rename accounts named OLD to NEW-'--pivot FIELDNAME'--     use some other field or tag for the account name-'-I --ignore-assertions'--     disable balance assertion checks (note: does not disable balance-     assignments)-'-s --strict'--     do extra error checking (check that all posted accounts are-     declared)---File: hledger-web.info,  Node: General reporting options,  Prev: General input options,  Up: OPTIONS--1.3 General reporting options-=============================--'-b --begin=DATE'--     include postings/txns on or after this date (will be adjusted to-     preceding subperiod start when using a report interval)-'-e --end=DATE'--     include postings/txns before this date (will be adjusted to-     following subperiod end when using a report interval)-'-D --daily'--     multiperiod/multicolumn report by day-'-W --weekly'--     multiperiod/multicolumn report by week-'-M --monthly'--     multiperiod/multicolumn report by month-'-Q --quarterly'--     multiperiod/multicolumn report by quarter-'-Y --yearly'--     multiperiod/multicolumn report by year-'-p --period=PERIODEXP'--     set start date, end date, and/or reporting interval all at once-     using period expressions syntax-'--date2'--     match the secondary date instead (see command help for other-     effects)-'--today=DATE'--     override today's date (affects relative smart dates, for-     tests/examples)-'-U --unmarked'--     include only unmarked postings/txns (can combine with -P or -C)-'-P --pending'--     include only pending postings/txns-'-C --cleared'--     include only cleared postings/txns-'-R --real'--     include only non-virtual postings-'-NUM --depth=NUM'--     hide/aggregate accounts or postings more than NUM levels deep-'-E --empty'--     show items with zero amount, normally hidden (and vice-versa in-     hledger-ui/hledger-web)-'-B --cost'--     convert amounts to their cost/selling amount at transaction time-'-V --market'--     convert amounts to their market value in default valuation-     commodities-'-X --exchange=COMM'--     convert amounts to their market value in commodity COMM-'--value'--     convert amounts to cost or market value, more flexibly than-     -B/-V/-X-'--infer-equity'--     infer conversion equity postings from costs-'--infer-costs'--     infer costs from conversion equity postings-'--infer-market-prices'--     use costs as additional market prices, as if they were P directives-'--forecast'--     generate transactions from periodic rules, between the latest-     recorded txn and 6 months from today, or during the specified-     PERIOD (= is required).  Auto posting rules will be applied to-     these transactions as well.  Also, in hledger-ui make future-dated-     transactions visible.-'--auto'--     generate extra postings by applying auto posting rules to all txns-     (not just forecast txns)-'--verbose-tags'--     add visible tags indicating transactions or postings which have-     been generated/modified-'--commodity-style'+   hledger-web also supports many of hledger's general options: -     Override the commodity style in the output for the specified-     commodity.  For example 'EUR1.000,00'.-'--color=WHEN (or --colour=WHEN)'+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 -     Should color-supporting commands use ANSI color codes in text-     output.  'auto' (default): whenever stdout seems to be a-     color-supporting terminal.  'always' or 'yes': always, useful eg-     when piping output into 'less -R'. 'never' or 'no': never.  A-     NO_COLOR environment variable overrides this.-'--pretty[=WHEN]'+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) -     Show prettier output, e.g.  using unicode box-drawing characters.-     Accepts 'yes' (the default) or 'no' ('y', 'n', 'always', 'never'-     also work).  If you provide an argument you must use '=', e.g.-     '-pretty=yes'.+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 -   When a reporting option appears more than once in the command line,-the last one takes precedence.+   hledger-web shows accounts with zero balances by default (like+'hledger-ui', and unlike 'hledger').  Using the '-E/--empty' flag will+reverse this behaviour.  If you see accounts which appear to have a zero+balance, but cannot be hidden with '-E', it's because they have a+mixed-cost balance, which looks like zero when costs are hidden.+(hledger-web does not show costs.) -   Some reporting options can also be written as query arguments.+   Reporting options and/or query arguments can be used to set an+initial query, which although not shown in the UI, will restrict the+data shown (in addition to any search query entered in the UI).   File: hledger-web.info,  Node: PERMISSIONS,  Next: EDITING UPLOADING DOWNLOADING,  Prev: OPTIONS,  Up: Top@@ -472,7 +355,8 @@    Most of the JSON corresponds to hledger's data types; for details of what the fields mean, see the Hledger.Data.Json haddock docs and click on the various data types, eg Transaction.  And for a higher level-understanding, see the journal docs.+understanding, see the journal docs.  There is also a basic OpenAPI+specification.     In some cases there is outer JSON corresponding to a "Report" type. To understand that, go to the Hledger.Web.Handler.MiscR haddock and look@@ -638,30 +522,24 @@  Tag Table: Node: Top223-Node: OPTIONS2577-Ref: #options2682-Node: General help options5647-Ref: #general-help-options5797-Node: General input options6079-Ref: #general-input-options6265-Node: General reporting options6922-Ref: #general-reporting-options7087-Node: PERMISSIONS10477-Ref: #permissions10616-Node: EDITING UPLOADING DOWNLOADING11828-Ref: #editing-uploading-downloading12009-Node: RELOADING12843-Ref: #reloading12977-Node: JSON API13410-Ref: #json-api13525-Node: DEBUG OUTPUT19013-Ref: #debug-output19138-Node: Debug output19165-Ref: #debug-output-119266-Node: ENVIRONMENT19683-Ref: #environment19802-Node: BUGS19919-Ref: #bugs20003+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  End Tag Table 

@@ -0,0 +1,32 @@+# hledger-web++> A web interface and API for `hledger`, a robust, friendly plain text accounting app.+> More information: <https://hledger.org/hledger-web.html>.++- Start the web app, and a browser if possible, for local viewing and adding only:++`hledger-web`++- As above but with a specified file, and allow editing of existing data:++`hledger-web --file {{path/to/file.journal}} --allow edit`++- Start just the web app, and accept incoming connections to the specified host and port:++`hledger-web --serve --host {{my.host.name}} --port 8000`++- Start just the web app's JSON API, and allow only read access:++`hledger-web --serve-api --host {{my.host.name}} --allow view`++- Show amounts converted to current market value in your base currency when known:++`hledger-web --value now --infer-market-prices`++- Show the manual in Info format if possible:++`hledger-web --info`++- Display help:++`hledger-web --help`

@@ -2,15 +2,17 @@ HLEDGER-WEB(1)               hledger User Manuals               HLEDGER-WEB(1)  NAME-       hledger-web - robust, friendly plain text accounting (Web version)+       hledger-web  -  web  interface  and API for hledger, a robust, friendly+       plain text accounting app.  SYNOPSIS-       hledger-web    [--serve|--serve-api] [OPTS] [ARGS]-       hledger web -- [--serve|--serve-api] [OPTS] [ARGS]+       hledger-web    [OPTS] [QUERY]+       or+       hledger web -- [OPTS] [QUERY]  DESCRIPTION-       This  manual  is for hledger's web interface, version 1.33.1.  See also-       the hledger manual for common concepts and file formats.+       This manual is for hledger's web interface, version 1.34.  See also the+       hledger manual for common concepts and file formats.         hledger is a robust, user-friendly, cross-platform set of programs  for        tracking  money,  time,  or any other commodity, using double-entry ac-@@ -54,50 +56,43 @@ OPTIONS        hledger-web provides the following options: -       --serve-              serve and log requests, don't browse or auto-exit after timeout--       --serve-api-              like --serve, but serve only the JSON web API, not the web UI--       --allow=view|add|edit-              set the user's access level for changing  data  (default:  add).-              It  also  accepts sandstorm for use on that platform (reads per--              missions from the X-Sandstorm-Permissions request header).--       --cors=ORIGIN-              allow cross-origin requests from the specified  origin;  setting-              ORIGIN to "*" allows requests from any origin--       --host=IPADDR-              listen on this IP address (default: 127.0.0.1)+              Flags:+                   --serve --server       serve and log requests, don't browse or auto-exit+                   --serve-api            like --serve, but serve only the JSON web API,+                                          not the web UI+                   --allow=view|add|edit  set the user's access level for changing data+                                          (default: `add`). It also accepts `sandstorm` for+                                          use on that platform (reads permissions from the+                                          `X-Sandstorm-Permissions` request header).+                   --cors=ORIGIN          allow cross-origin requests from the specified+                                          origin; setting ORIGIN to "*" allows requests from+                                          any origin+                   --host=IPADDR          listen on this IP address (default: 127.0.0.1)+                   --port=PORT            listen on this TCP port (default: 5000)+                   --socket=SOCKET        listen on the given unix socket instead of an IP+                                          address and port (unix only; implies --serve)+                   --base-url=BASEURL     set the base url (default: http://IPADDR:PORT)+                   --test                 run hledger-web's tests and exit. hspec test+                                          runner args may follow a --, eg: hledger-web --test+                                          -- --help -       By  default the server listens on IP address 127.0.0.1, which is acces--       sible only to requests from the local machine..  You can use --host  to-       listen  on  a  different address configured on the machine, eg to allow-       access from other machines.  The special address 0.0.0.0 causes  it  to-       listen on all addresses configured on the machine.+       By default hledger-web listens only on IP address 127.0.0.1,  which  be+       accessed only from the local machine. -       --port=PORT-              listen on this TCP port (default: 5000)+       To allow access from elsewhere, use --host to specify an externally ac-+       cessible  address  configured  on  this  machine,  The  special address+       0.0.0.0 causes it to listen on all of this machine's addresses. -       Similarly,  you can use --port to listen on a TCP port other than 5000.-       This is useful if you want to run multiple hledger-web instances  on  a+       Similarly, you can use --port to listen on a TCP port other than  5000.+       This  is  useful if you want to run multiple hledger-web instances on a        machine. -       --socket=SOCKETFILE-              listen  on  the  given  unix socket instead of an IP address and-              port (unix only; implies --serve)-        When --socket is used,  hledger-web  creates  and  communicates  via  a        socket  file  instead of a TCP port.  This can be more secure, respects        unix file permissions, and makes certain use cases easier, such as run-        ning per-user instances behind an nginx reverse proxy.  (Eg: proxy_pass        http://unix:/tmp/hledger/${remote_user}.socket;.) -       --base-url=URL-              set the base url (default: http://IPADDR:PORT).-        You can use --base-url to change the protocol, hostname, port and  path        that  appear in hledger-web's hyperlinks.  This is useful eg when inte-        grating  hledger-web  within  a  larger  website.    The   default   is@@ -105,177 +100,96 @@        port (or http://HOST if PORT is 80).  Note this affects url  generation        but not route parsing. -       --test run  hledger-web's  tests  and exit.  hspec test runner args may-              follow a --, eg: hledger-web --test -- --help--       hledger-web also supports many of hledger's general options.  Query op--       tions and arguments may be used to set an  initial  filter,  which  al--       though  not  shown in the UI, will restrict the data shown, in addition-       to any search query entered in the UI.--       Note that hledger-web shows accounts with  zero  balances  by  default,-       like  hledger-ui  (and  unlike  hledger).  Using the -E/--empty flag at-       startup will hide them.--       If you see accounts which appear to have a zero balance, but cannot  be-       hidden  with  -E: these have a mixed-cost balance which looks like zero-       when costs are hidden.  Currently hledger-web does not  show  costs  at-       all.--   General help options-       -h --help-              show general or COMMAND help--       --man  show general or COMMAND user manual with man--       --info show general or COMMAND user manual with info--       --version-              show general or ADDONCMD version--       --debug[=N]-              show debug output (levels 1-9, default: 1)--   General input options-       -f FILE --file=FILE-              use  a  different  input  file.   For  stdin,  use  -  (default:-              $LEDGER_FILE or $HOME/.hledger.journal)--       --rules-file=RULESFILE-              Conversion  rules  file  to  use  when  reading  CSV   (default:-              FILE.rules)--       --separator=CHAR-              Field separator to expect when reading CSV (default: ',')--       --alias=OLD=NEW-              rename accounts named OLD to NEW--       --pivot FIELDNAME-              use some other field or tag for the account name--       -I --ignore-assertions-              disable balance assertion checks (note: does not disable balance-              assignments)--       -s --strict-              do  extra error checking (check that all posted accounts are de--              clared)--   General reporting options-       -b --begin=DATE-              include postings/txns on or after this date (will be adjusted to-              preceding subperiod start when using a report interval)--       -e --end=DATE-              include postings/txns before this date (will be adjusted to fol--              lowing subperiod end when using a report interval)--       -D --daily-              multiperiod/multicolumn report by day--       -W --weekly-              multiperiod/multicolumn report by week--       -M --monthly-              multiperiod/multicolumn report by month--       -Q --quarterly-              multiperiod/multicolumn report by quarter--       -Y --yearly-              multiperiod/multicolumn report by year--       -p --period=PERIODEXP-              set start date, end date, and/or reporting interval all at  once-              using period expressions syntax--       --date2-              match the secondary date instead (see command help for other ef--              fects)--       --today=DATE-              override   today's  date  (affects  relative  smart  dates,  for-              tests/examples)--       -U --unmarked-              include only unmarked postings/txns (can combine with -P or -C)--       -P --pending-              include only pending postings/txns--       -C --cleared-              include only cleared postings/txns--       -R --real-              include only non-virtual postings--       -NUM --depth=NUM-              hide/aggregate accounts or postings more than NUM levels deep--       -E --empty-              show items with zero amount, normally hidden (and vice-versa  in-              hledger-ui/hledger-web)--       -B --cost-              convert amounts to their cost/selling amount at transaction time--       -V --market-              convert  amounts to their market value in default valuation com--              modities--       -X --exchange=COMM-              convert amounts to their market value in commodity COMM--       --value-              convert amounts to cost or  market  value,  more  flexibly  than-              -B/-V/-X--       --infer-equity-              infer conversion equity postings from costs--       --infer-costs-              infer costs from conversion equity postings--       --infer-market-prices-              use  costs as additional market prices, as if they were P direc--              tives--       --forecast-              generate transactions from periodic rules,  between  the  latest-              recorded  txn  and  6 months from today, or during the specified-              PERIOD (= is required).  Auto posting rules will be  applied  to-              these  transactions  as  well.   Also,  in  hledger-ui  make fu--              ture-dated transactions visible.--       --auto generate extra postings by applying auto posting  rules  to  all-              txns (not just forecast txns)--       --verbose-tags-              add  visible tags indicating transactions or postings which have-              been generated/modified+       hledger-web also supports many of hledger's general options: -       --commodity-style-              Override the commodity style in the  output  for  the  specified-              commodity.  For example 'EUR1.000,00'.+              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 -       --color=WHEN (or --colour=WHEN)-              Should  color-supporting  commands  use ANSI color codes in text-              output.   'auto'  (default):  whenever  stdout  seems  to  be  a-              color-supporting terminal.  'always' or 'yes': always, useful eg-              when  piping  output into 'less -R'.  'never' or 'no': never.  A-              NO_COLOR environment variable overrides this.+              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) -       --pretty[=WHEN]-              Show prettier output, e.g.  using  unicode  box-drawing  charac--              ters.   Accepts 'yes' (the default) or 'no' ('y', 'n', 'always',-              'never' also work).  If you provide an  argument  you  must  use-              '=', e.g.  '--pretty=yes'.+              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 -       When a reporting option appears more than once in the command line, the-       last one takes precedence.+       hledger-web   shows  accounts  with  zero  balances  by  default  (like+       hledger-ui, and unlike hledger).  Using the -E/--empty  flag  will  re-+       verse  this behaviour.  If you see accounts which appear to have a zero+       balance, but cannot be  hidden  with  -E,  it's  because  they  have  a+       mixed-cost  balance,  which  looks  like  zero  when  costs are hidden.+       (hledger-web does not show costs.) -       Some reporting options can also be written as query arguments.+       Reporting options and/or query arguments can be used to set an  initial+       query, which although not shown in the UI, will restrict the data shown+       (in addition to any search query entered in the UI).  PERMISSIONS        By  default,  hledger-web  allows  anyone  who can reach it to view the@@ -401,7 +315,8 @@        Most of the JSON corresponds to hledger's data types;  for  details  of        what  the fields mean, see the Hledger.Data.Json haddock docs and click        on the various data types, eg Transaction.  And for a higher level  un--       derstanding, see the journal docs.+       derstanding, see the journal docs.  There is also a basic OpenAPI spec-+       ification.         In some cases there is outer JSON corresponding to a "Report" type.  To        understand  that,  go to the Hledger.Web.Handler.MiscR haddock and look@@ -558,4 +473,4 @@ SEE ALSO        hledger(1), hledger-ui(1), hledger-web(1), ledger(1) -hledger-web-1.33.1                 May 2024                     HLEDGER-WEB(1)+hledger-web-1.34                   June 2024                    HLEDGER-WEB(1)

@@ -1,11344 +1,11304 @@ .\"t -.TH "HLEDGER" "1" "May 2024" "hledger-1.33.1 " "hledger User Manuals"----.SH NAME-hledger \- robust, friendly plain text accounting (CLI version)-.SH SYNOPSIS-\f[CR]hledger\f[R]-.PD 0-.P-.PD-\f[CR]hledger COMMAND     [OPTS] [ARGS]\f[R]-.PD 0-.P-.PD-\f[CR]hledger ADDONCMD \-\- [OPTS] [ARGS]\f[R]-.SH DESCRIPTION-hledger is a robust, user\-friendly, cross\-platform set of programs for-tracking money, time, or any other commodity, using double\-entry-accounting and a simple, editable file format.-hledger is inspired by and largely compatible with ledger(1), and-largely interconvertible with beancount(1).-.PP-This manual is for hledger\[aq]s command line interface, version 1.33.1.-It also describes the common options, file formats and concepts used by-all hledger programs.-It might accidentally teach you some bookkeeping/accounting as well!-You don\[aq]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-.PD 0-.P-.PD-\f[CR]hledger \-\-man\f[R], \f[CR]hledger \-\-info\f[R] or-\f[CR]hledger help [TOPIC]\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).-Many reports are available, as subcommands.-hledger will also detect other \f[CR]hledger\-*\f[R] executables as-extra subcommands.-.PP-hledger usually reads from (and appends to) a journal file specified by-the \f[CR]LEDGER_FILE\f[R] environment variable (defaulting to-\f[CR]$HOME/.hledger.journal\f[R]); or you can specify files with-\f[CR]\-f\f[R] options.-It can also read timeclock files, timedot files, or any CSV/SSV/TSV file-with a date field.-.PP-Here is a small journal file describing one transaction:-.IP-.EX-2015\-10\-16 bought food-  expenses:food          $10-  assets:cash-.EE-.PP-Transactions are dated movements of money (etc.)-between two or more \f[I]accounts\f[R]: bank accounts, your wallet,-revenue/expense categories, people, etc.-You can choose any account names you wish, using \f[CR]:\f[R] to-indicate subaccounts.-There must be at least two spaces between account name and amount.-Positive amounts are inflow to that account (\f[I]debit\f[R]), negatives-are outflow from it (\f[I]credit\f[R]).-(Some reports show revenue, liability and equity account balances as-negative numbers as a result; this is normal.)-.PP-hledger\[cq]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).-.PP-To get started, run \f[CR]hledger add\f[R] and follow the prompts, or-save some entries like the above in \f[CR]$HOME/.hledger.journal\f[R],-then try commands like:-.IP-.EX-$ hledger print \-x-$ hledger aregister assets-$ hledger balance-$ hledger balancesheet-$ hledger incomestatement-.EE-.PP-Run \f[CR]hledger\f[R] to list the commands.-See also the \[dq]Starting a journal file\[dq] and \[dq]Setting opening-balances\[dq] sections in PART 5: COMMON TASKS.-.SH PART 1: USER INTERFACE-.SH Input-hledger reads one or more data files, each time you run it.-You can specify a file with \f[CR]\-f\f[R], like so-.IP-.EX-$ hledger \-f FILE print-.EE-.PP-Files are most often in hledger\[aq]s journal format, with the-\f[CR].journal\f[R] file extension (\f[CR].hledger\f[R] or \f[CR].j\f[R]-also work); these files describe transactions, like an accounting-general journal.-.PP-When no file is specified, hledger looks for \f[CR].hledger.journal\f[R]-in your home directory.-.PP-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\[aq]s not-required, but helps keep things fast and organised).-So we usually configure a different journal file, by setting the-\f[CR]LEDGER_FILE\f[R] environment variable, to something like-\f[CR]\[ti]/finance/2023.journal\f[R].-For more about how to do that on your system, see Common tasks > Setting-LEDGER_FILE.-.SS Text encoding-Data files containing non\-ascii characters must use UTF\-8 encoding.-An optional byte order mark (BOM) is allowed, at the beginning of the-file (only).-.PP-Also, your system should be configured with a locale that can decode-UTF\-8 text.-On some unix systems, you may need set the \f[CR]LANG\f[R] environment-variable, eg.-You can read more about this in Unicode characters, below.-.PP-On unix systems you can check a file\[aq]s encoding with the-\f[CR]file\f[R] command.-If you need to import from a UTF\-16\-encoded CSV file, say, you can-convert it to UTF\-8 with the \f[CR]iconv\f[R] command.-.SS Data formats-Usually the data file is in hledger\[aq]s journal format, but it can be-in any of the supported file formats, which currently are:-.PP-.TS-tab(@);-lw(13.5n) lw(33.0n) lw(23.5n).-T{-Reader:-T}@T{-Reads:-T}@T{-Automatically used for files with extensions:-T}-_-T{-\f[CR]journal\f[R]-T}@T{-hledger journal files and some Ledger journals, for transactions-T}@T{-\f[CR].journal\f[R] \f[CR].j\f[R] \f[CR].hledger\f[R] \f[CR].ledger\f[R]-T}-T{-\f[CR]timeclock\f[R]-T}@T{-timeclock files, for precise time logging-T}@T{-\f[CR].timeclock\f[R]-T}-T{-\f[CR]timedot\f[R]-T}@T{-timedot files, for approximate time logging-T}@T{-\f[CR].timedot\f[R]-T}-T{-\f[CR]csv\f[R]-T}@T{-Comma or other character separated values, for data import-T}@T{-\f[CR].csv\f[R]-T}-T{-\f[CR]ssv\f[R]-T}@T{-Semicolon separated values-T}@T{-\f[CR].ssv\f[R]-T}-T{-\f[CR]tsv\f[R]-T}@T{-Tab separated values-T}@T{-\f[CR].tsv\f[R]-T}-T{-\f[CR]rules\f[R]-T}@T{-CSV/SSV/TSV/other separated values, alternate way-T}@T{-\f[CR].rules\f[R]-T}-.TE-.PP-These formats are described in more detail below.-.PP-hledger detects the format automatically based on the file extensions-shown above.-If it can\[aq]t recognise the file extension, it assumes-\f[CR]journal\f[R] format.-So for non\-journal files, it\[aq]s important to use a recognised file-extension, so as to either read successfully or to show relevant error-messages.-.PP-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:-.IP-.EX-$ hledger \-f tsv:/some/file.dat stats-.EE-.SS Standard input-The file name \f[CR]\-\f[R] means standard input:-.IP-.EX-$ cat FILE | hledger \-f\- print-.EE-.PP-If reading non\-journal data in this way, you\[aq]ll need to add a file-format prefix, like:-.IP-.EX-$ echo \[aq]i 2009/13/1 08:00:00\[aq] | hledger print \-f timeclock:\--.EE-.SS Multiple files-You can specify multiple \f[CR]\-f\f[R] options, to read multiple files-as one big journal.-When doing this, note that certain features (described below) will be-affected:-.IP \[bu] 2-Balance assertions will not see the effect of transactions in previous-files.-(Usually this doesn\[aq]t matter as each file will set the corresponding-opening balances.)-.IP \[bu] 2-Some directives will not affect previous or subsequent files.-.PP-If needed, you can work around these by using a single parent file which-includes the others, or concatenating the files into one, eg:-\f[CR]cat a.journal b.journal | hledger \-f\- CMD\f[R].-.SS 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:-.IP \[bu] 2-Are the input files parseable, with valid syntax ?-.IP \[bu] 2-Are all transactions balanced ?-.IP \[bu] 2-Do all balance assertions pass ?-.PP-With the \f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R] flag, additional checks-are performed:-.IP \[bu] 2-Are all accounts posted to, declared with an \f[CR]account\f[R]-directive ?-(Account error checking)-.IP \[bu] 2-Are all commodities declared with a \f[CR]commodity\f[R] directive ?-(Commodity error checking)-.IP \[bu] 2-Are all commodity conversions declared explicitly ?-.PP-You can use the check command to run individual checks \-\- the ones-listed above and some more.-.SH 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.-.PP-To show the commands list, run \f[CR]hledger\f[R] with no arguments.-The commands are described in detail in PART 4: COMMANDS, below.-.PP-To use a particular command, run-\f[CR]hledger CMD [CMDOPTS] [CMDARGS]\f[R],-.IP \[bu] 2-CMD is the full command name, or its standard abbreviation shown in the-commands list, or any unambiguous prefix of the name.-.IP \[bu] 2-CMDOPTS are command\-specific options, if any.-Command\-specific options must be written after the command name.-Eg: \f[CR]hledger print \-x\f[R].-.IP \[bu] 2-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: \f[CR]hledger reg assets:checking\f[R].-.PP-To list a command\[aq]s options, arguments, and documentation in the-terminal, run \f[CR]hledger CMD \-h\f[R].-Eg: \f[CR]hledger bal \-h\f[R].-.SS Add\-on commands-In addition to the built\-in commands, you can install \f[I]add\-on-commands\f[R]: programs or scripts named \[dq]hledger\-SOMETHING\[dq],-which will also appear in hledger\[aq]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\[aq]s bin/ directory, documented at-https://hledger.org/scripts.html.-.PP-More precisely, add\-on commands are programs or scripts in your-shell\[aq]s PATH, whose name starts with \[dq]hledger\-\[dq] and ends-with no extension or a recognised extension (\[dq].bat\[dq],-\[dq].com\[dq], \[dq].exe\[dq], \[dq].hs\[dq], \[dq].js\[dq],-\[dq].lhs\[dq], \[dq].lua\[dq], \[dq].php\[dq], \[dq].pl\[dq],-\[dq].py\[dq], \[dq].rb\[dq], \[dq].rkt\[dq], or \[dq].sh\[dq]), and (on-unix and mac) which has executable permission for the current user.-.PP-You can run add\-on commands using hledger, much like built\-in-commands:-\f[CR]hledger ADDONCMD [\-\- ADDONCMDOPTS] [ADDONCMDARGS]\f[R].-But note the double hyphen argument, required before add\-on\-specific-options.-Eg: \f[CR]hledger ui \-\- \-\-watch\f[R] or-\f[CR]hledger web \-\- \-\-serve\f[R].-If this causes difficulty, you can always run the add\-on directly,-without using \f[CR]hledger\f[R]: \f[CR]hledger\-ui \-\-watch\f[R] or-\f[CR]hledger\-web \-\-serve\f[R].-.SH Options-Run \f[CR]hledger \-h\f[R] to see general command line help, and general-options which are common to most hledger commands.-These options can be written anywhere on the command line.-They can be grouped into help, input, and reporting options:-.SS General help options-.TP-\f[CR]\-h \-\-help\f[R]-show general or COMMAND help-.TP-\f[CR]\-\-man\f[R]-show general or COMMAND user manual with man-.TP-\f[CR]\-\-info\f[R]-show general or COMMAND user manual with info-.TP-\f[CR]\-\-version\f[R]-show general or ADDONCMD version-.TP-\f[CR]\-\-debug[=N]\f[R]-show debug output (levels 1\-9, default: 1)-.SS General input options-.TP-\f[CR]\-f FILE \-\-file=FILE\f[R]-use a different input file.-For stdin, use \- (default: \f[CR]$LEDGER_FILE\f[R] or-\f[CR]$HOME/.hledger.journal\f[R])-.TP-\f[CR]\-\-rules\-file=RULESFILE\f[R]-Conversion rules file to use when reading CSV (default: FILE.rules)-.TP-\f[CR]\-\-separator=CHAR\f[R]-Field separator to expect when reading CSV (default: \[aq],\[aq])-.TP-\f[CR]\-\-alias=OLD=NEW\f[R]-rename accounts named OLD to NEW-.TP-\f[CR]\-\-pivot FIELDNAME\f[R]-use some other field or tag for the account name-.TP-\f[CR]\-I \-\-ignore\-assertions\f[R]-disable balance assertion checks (note: does not disable balance-assignments)-.TP-\f[CR]\-s \-\-strict\f[R]-do extra error checking (check that all posted accounts are declared)-.SS General reporting options-.TP-\f[CR]\-b \-\-begin=DATE\f[R]-include postings/txns on or after this date (will be adjusted to-preceding subperiod start when using a report interval)-.TP-\f[CR]\-e \-\-end=DATE\f[R]-include postings/txns before this date (will be adjusted to following-subperiod end when using a report interval)-.TP-\f[CR]\-D \-\-daily\f[R]-multiperiod/multicolumn report by day-.TP-\f[CR]\-W \-\-weekly\f[R]-multiperiod/multicolumn report by week-.TP-\f[CR]\-M \-\-monthly\f[R]-multiperiod/multicolumn report by month-.TP-\f[CR]\-Q \-\-quarterly\f[R]-multiperiod/multicolumn report by quarter-.TP-\f[CR]\-Y \-\-yearly\f[R]-multiperiod/multicolumn report by year-.TP-\f[CR]\-p \-\-period=PERIODEXP\f[R]-set start date, end date, and/or reporting interval all at once using-period expressions syntax-.TP-\f[CR]\-\-date2\f[R]-match the secondary date instead (see command help for other effects)-.TP-\f[CR]\-\-today=DATE\f[R]-override today\[aq]s date (affects relative smart dates, for-tests/examples)-.TP-\f[CR]\-U \-\-unmarked\f[R]-include only unmarked postings/txns (can combine with \-P or \-C)-.TP-\f[CR]\-P \-\-pending\f[R]-include only pending postings/txns-.TP-\f[CR]\-C \-\-cleared\f[R]-include only cleared postings/txns-.TP-\f[CR]\-R \-\-real\f[R]-include only non\-virtual postings-.TP-\f[CR]\-NUM \-\-depth=NUM\f[R]-hide/aggregate accounts or postings more than NUM levels deep-.TP-\f[CR]\-E \-\-empty\f[R]-show items with zero amount, normally hidden (and vice\-versa in-hledger\-ui/hledger\-web)-.TP-\f[CR]\-B \-\-cost\f[R]-convert amounts to their cost/selling amount at transaction time-.TP-\f[CR]\-V \-\-market\f[R]-convert amounts to their market value in default valuation commodities-.TP-\f[CR]\-X \-\-exchange=COMM\f[R]-convert amounts to their market value in commodity COMM-.TP-\f[CR]\-\-value\f[R]-convert amounts to cost or market value, more flexibly than \-B/\-V/\-X-.TP-\f[CR]\-\-infer\-equity\f[R]-infer conversion equity postings from costs-.TP-\f[CR]\-\-infer\-costs\f[R]-infer costs from conversion equity postings-.TP-\f[CR]\-\-infer\-market\-prices\f[R]-use costs as additional market prices, as if they were P directives-.TP-\f[CR]\-\-forecast\f[R]-generate transactions from periodic rules,-between the latest recorded txn and 6 months from today,-or during the specified PERIOD (= is required).-Auto posting rules will be applied to these transactions as well.-Also, in hledger\-ui make future\-dated transactions visible.-.TP-\f[CR]\-\-auto\f[R]-generate extra postings by applying auto posting rules to all txns (not-just forecast txns)-.TP-\f[CR]\-\-verbose\-tags\f[R]-add visible tags indicating transactions or postings which have been-generated/modified-.TP-\f[CR]\-\-commodity\-style\f[R]-Override the commodity style in the output for the specified commodity.-For example \[aq]EUR1.000,00\[aq].-.TP-\f[CR]\-\-color=WHEN (or \-\-colour=WHEN)\f[R]-Should color\-supporting commands use ANSI color codes in text output.-\[aq]auto\[aq] (default): whenever stdout seems to be a-color\-supporting terminal.-\[aq]always\[aq] or \[aq]yes\[aq]: always, useful eg when piping output-into \[aq]less \-R\[aq].-\[aq]never\[aq] or \[aq]no\[aq]: never.-A NO_COLOR environment variable overrides this.-.TP-\f[CR]\-\-pretty[=WHEN]\f[R]-Show prettier output, e.g.-using unicode box\-drawing characters.-Accepts \[aq]yes\[aq] (the default) or \[aq]no\[aq] (\[aq]y\[aq],-\[aq]n\[aq], \[aq]always\[aq], \[aq]never\[aq] also work).-If you provide an argument you must use \[aq]=\[aq], e.g.-\[aq]\-\-pretty=yes\[aq].-.PP-When a reporting option appears more than once in the command line, the-last one takes precedence.-.PP-Some reporting options can also be written as query arguments.-.SH Command line tips-Here are some details useful to know about for hledger command lines-(and elsewhere).-Feel free to skip this section until you need it.-.SS Option repetition-If options are repeated in a command line, hledger will generally use-the last (right\-most) occurence.-.SS Special characters-.SS Single escaping (shell metacharacters)-In shell command lines, characters significant to your shell \- such as-spaces, \f[CR]<\f[R], \f[CR]>\f[R], \f[CR](\f[R], \f[CR])\f[R],-\f[CR]|\f[R], \f[CR]$\f[R] and \f[CR]\[rs]\f[R] \- should be-\[dq]shell\-escaped\[dq] 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:-.IP-.EX-$ hledger register \[aq]credit card\[aq]-.EE-.PP-or:-.IP-.EX-$ hledger register credit\[rs] card-.EE-.PP-Windows users should keep in mind that \f[CR]cmd\f[R] treats single-quote as a regular character, so you should be using double quotes-exclusively.-PowerShell treats both single and double quotes as quotes.-.SS Double escaping (regular expression metacharacters)-Characters significant in regular expressions (described below) \- such-as \f[CR].\f[R], \f[CR]\[ha]\f[R], \f[CR]$\f[R], \f[CR][\f[R],-\f[CR]]\f[R], \f[CR](\f[R], \f[CR])\f[R], \f[CR]|\f[R], and-\f[CR]\[rs]\f[R] \- may need to be \[dq]regex\-escaped\[dq] if you-don\[aq]t want them to be interpreted by hledger\[aq]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 \f[CR]$\f[R] sign while using the bash shell:-.IP-.EX-$ hledger balance cur:\[aq]\[rs]$\[aq]-.EE-.PP-or:-.IP-.EX-$ hledger balance cur:\[rs]\[rs]$-.EE-.SS 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 \f[CR]$\f[R] sign while using the bash shell and-running an add\-on command (\f[CR]ui\f[R]):-.IP-.EX-$ hledger ui cur:\[aq]\[rs]\[rs]$\[aq]-.EE-.PP-or:-.IP-.EX-$ hledger ui cur:\[rs]\[rs]\[rs]\[rs]$-.EE-.PP-If you wondered why \f[I]four\f[R] backslashes, perhaps this helps:-.PP-.TS-tab(@);-l l.-T{-unescaped:-T}@T{-\f[CR]$\f[R]-T}-T{-escaped:-T}@T{-\f[CR]\[rs]$\f[R]-T}-T{-double\-escaped:-T}@T{-\f[CR]\[rs]\[rs]$\f[R]-T}-T{-triple\-escaped:-T}@T{-\f[CR]\[rs]\[rs]\[rs]\[rs]$\f[R]-T}-.TE-.PP-Or, you can avoid the extra escaping by running the add\-on executable-directly:-.IP-.EX-$ hledger\-ui cur:\[rs]\[rs]$-.EE-.SS 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:-.IP \[bu] 2-an \[at]argumentfile-.IP \[bu] 2-hledger\-ui\[aq]s filter field-.IP \[bu] 2-hledger\-web\[aq]s search form-.IP \[bu] 2-GHCI\[aq]s prompt (used by developers).-.SS Unicode characters-hledger is expected to handle non\-ascii characters correctly:-.IP \[bu] 2-they should be parsed correctly in input files and on the command line,-by all hledger tools (add, iadd, hledger\-web\[aq]s search/add/edit-forms, etc.)-.IP \[bu] 2-they should be displayed correctly by all hledger tools, and on\-screen-alignment should be preserved.-.PP-This requires a well\-configured environment.-Here are some tips:-.IP \[bu] 2-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:-\f[CR]export LANG=en_US.UTF\-8\f[R].-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).-.IP \[bu] 2-your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..)-must support unicode-.IP \[bu] 2-the terminal must be using a font which includes the required unicode-glyphs-.IP \[bu] 2-the terminal should be configured to display wide characters as double-width (for report alignment)-.IP \[bu] 2-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).-.SS Regular expressions-A regular expression (regexp) is a small piece of text where certain-characters (like \f[CR].\f[R], \f[CR]\[ha]\f[R], \f[CR]$\f[R],-\f[CR]+\f[R], \f[CR]*\f[R], \f[CR]()\f[R], \f[CR]|\f[R], \f[CR][]\f[R],-\f[CR]\[rs]\f[R]) 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.-.PP-hledger supports regexps whenever you are entering a pattern to match-something, eg in query arguments, account aliases, CSV if rules,-hledger\-web\[aq]s search form, hledger\-ui\[aq]s \f[CR]/\f[R] search,-etc.-You may need to wrap them in quotes, especially at the command line (see-Special characters above).-Here are some examples:-.PP-Account name queries (quoted for command line use):-.IP-.EX-Regular expression:  Matches:-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--bank                 assets:bank, assets:bank:savings, expenses:art:banksy, ...-:bank                assets:bank:savings, expenses:art:banksy-:bank:               assets:bank:savings-\[aq]\[ha]bank\[aq]              none of those ( \[ha] matches beginning of text )-\[aq]bank$\[aq]              assets:bank   ( $ matches end of text )-\[aq]big \[rs]$ bank\[aq]        big $ bank    ( \[rs] disables following character\[aq]s special meaning )-\[aq]\[rs]bbank\[rs]b\[aq]           assets:bank, assets:bank:savings  ( \[rs]b matches word boundaries )-\[aq](sav|check)ing\[aq]     saving or checking  ( (|) matches either alternative )-\[aq]saving|checking\[aq]    saving or checking  ( outer parentheses are not needed )-\[aq]savings?\[aq]           saving or savings   ( ? matches 0 or 1 of the preceding thing )-\[aq]my +bank\[aq]           my bank, my  bank, ... ( + matches 1 or more of the preceding thing )-\[aq]my *bank\[aq]           mybank, my bank, my  bank, ... ( * matches 0 or more of the preceding thing )-\[aq]b.nk\[aq]               bank, bonk, b nk, ... ( . matches any character )-.EE-.PP-Some other queries:-.IP-.EX-desc:\[aq]amazon|amzn|audible\[aq]  Amazon transactions-cur:EUR              amounts with commodity symbol containing EUR-cur:\[aq]\[rs]$\[aq]             amounts with commodity symbol containing $-cur:\[aq]\[ha]\[rs]$$\[aq]           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-.EE-.PP-Account name aliases: accept \f[CR].\f[R] instead of \f[CR]:\f[R] as-account separator:-.IP-.EX-alias /\[rs]./=:         replaces all periods in account names with colons-.EE-.PP-Show multiple top\-level accounts combined as one:-.IP-.EX-\-\-alias=\[aq]/\[ha][\[ha]:]+/=combined\[aq]  ( [\[ha]:] matches any character other than : )-.EE-.PP-Show accounts with the second\-level part removed:-.IP-.EX-\-\-alias \[aq]/\[ha]([\[ha]:]+):[\[ha]:]+/ = \[rs]1\[aq]-                     match a top\-level account and a second\-level account-                     and replace those with just the top\-level account-                     ( \[rs]1 in the replacement text means \[dq]whatever was matched-                     by the first parenthesised part of the regexp\[dq]-.EE-.PP-CSV rules: match CSV records containing dining\-related MCC codes:-.IP-.EX-if \[rs]?MCC581[124]-.EE-.PP-Match CSV records with a specific amount around the end/start of month:-.IP-.EX-if %amount \[rs]b3\[rs].99-&  %date   (29|30|31|01|02|03)$-.EE-.SS hledger\[aq]s regular expressions-hledger\[aq]s regular expressions come from the regex\-tdfa library.-If they\[aq]re not doing what you expect, it\[aq]s important to know-exactly what they support:-.IP "1." 3-they are case insensitive-.IP "2." 3-they are infix matching (they do not need to match the entire thing-being matched)-.IP "3." 3-they are POSIX ERE (extended regular expressions)-.IP "4." 3-they also support GNU word boundaries (\f[CR]\[rs]b\f[R],-\f[CR]\[rs]B\f[R], \f[CR]\[rs]<\f[R], \f[CR]\[rs]>\f[R])-.IP "5." 3-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 \f[CR]\[rs]1\f[R], it will match the digit-\f[CR]1\f[R].-.IP "6." 3-they do not support mode modifiers (\f[CR](?s)\f[R]), character classes-(\f[CR]\[rs]w\f[R], \f[CR]\[rs]d\f[R]), or anything else not mentioned-above.-.PP-Some things to note:-.IP \[bu] 2-In the \f[CR]alias\f[R] directive and \f[CR]\-\-alias\f[R] option,-regular expressions must be enclosed in forward slashes-(\f[CR]/REGEX/\f[R]).-Elsewhere in hledger, these are not required.-.IP \[bu] 2-In queries, to match a regular expression metacharacter like-\f[CR]$\f[R] as a literal character, prepend a backslash.-Eg to search for amounts with the dollar sign in hledger\-web, write-\f[CR]cur:\[rs]$\f[R].-.IP \[bu] 2-On the command line, some metacharacters like \f[CR]$\f[R] have a-special meaning to the shell and so must be escaped at least once more.-See Special characters.-.SS Argument files-You can save a set of command line options and arguments in a file, and-then reuse them by writing \f[CR]\[at]FILENAME\f[R] as a command line-argument.-Eg: \f[CR]hledger bal \[at]foo.args\f[R].-.PP-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.-For the special characters mentioned above, use one less level of-quoting than you would at the command prompt.-.SH Output-.SS 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:-.IP-.EX-$ hledger print > foo.txt-.EE-.PP-Some commands (print, register, stats, the balance commands) also-provide the \f[CR]\-o/\-\-output\-file\f[R] option, which does the same-thing without needing the shell.-Eg:-.IP-.EX-$ hledger print \-o foo.txt-$ hledger print \-o \-        # write to stdout (the default)-.EE-.SS Output format-Some commands offer other kinds of output, not just text on the-terminal.-Here are those commands and the formats currently supported:-.PP-.TS-tab(@);-lw(16.1n) lw(14.5n) lw(14.5n) lw(16.1n) lw(4.8n) lw(4.0n).-T{-\--T}@T{-txt-T}@T{-csv/tsv-T}@T{-html-T}@T{-json-T}@T{-sql-T}-_-T{-aregister-T}@T{-Y-T}@T{-Y-T}@T{-Y-T}@T{-Y-T}@T{-T}-T{-balance-T}@T{-Y \f[I]1\f[R]-T}@T{-Y \f[I]1\f[R]-T}@T{-Y \f[I]1,2\f[R]-T}@T{-Y-T}@T{-T}-T{-balancesheet-T}@T{-Y \f[I]1\f[R]-T}@T{-Y \f[I]1\f[R]-T}@T{-Y \f[I]1\f[R]-T}@T{-Y-T}@T{-T}-T{-balancesheetequity-T}@T{-Y \f[I]1\f[R]-T}@T{-Y \f[I]1\f[R]-T}@T{-Y \f[I]1\f[R]-T}@T{-Y-T}@T{-T}-T{-cashflow-T}@T{-Y \f[I]1\f[R]-T}@T{-Y \f[I]1\f[R]-T}@T{-Y \f[I]1\f[R]-T}@T{-Y-T}@T{-T}-T{-incomestatement-T}@T{-Y \f[I]1\f[R]-T}@T{-Y \f[I]1\f[R]-T}@T{-Y \f[I]1\f[R]-T}@T{-Y-T}@T{-T}-T{-print-T}@T{-Y-T}@T{-Y-T}@T{-T}@T{-Y-T}@T{-Y-T}-T{-register-T}@T{-Y-T}@T{-Y-T}@T{-T}@T{-Y-T}@T{-T}-.TE-.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:-.IP-.EX-$ hledger print \-O csv    # print CSV on stdout-.EE-.PP-or by the filename extension of an output file specified with the-\f[CR]\-o/\-\-output\-file=FILE.FMT\f[R] option:-.IP-.EX-$ hledger balancesheet \-o foo.csv    # write CSV to foo.csv-.EE-.PP-The \f[CR]\-O\f[R] option can be combined with \f[CR]\-o\f[R] to-override the file extension, if needed:-.IP-.EX-$ hledger balancesheet \-o foo.txt \-O csv    # write CSV to foo.txt-.EE-.PP-Some notes about the various output formats:-.SS CSV output-.IP \[bu] 2-In CSV output, digit group marks (such as thousands separators) are-disabled automatically.-.SS HTML output-.IP \[bu] 2-HTML output can be styled by an optional \f[CR]hledger.css\f[R] file in-the same directory.-.SS JSON output-.IP \[bu] 2-This is not yet much used; real\-world feedback is welcome.-.IP \[bu] 2-Our JSON is rather large and verbose, since it is a faithful-representation of hledger\[aq]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.-.IP \[bu] 2-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\[aq]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)-.SS SQL output-.IP \[bu] 2-This is not yet much used; real\-world feedback is welcome.-.IP \[bu] 2-SQL output is expected to work at least with SQLite, MySQL and Postgres.-.IP \[bu] 2-For SQLite, it will be more useful if you modify the generated-\f[CR]id\f[R] field to be a PRIMARY KEY.-Eg:-.RS 2-.IP-.EX-$ hledger print \-O sql | sed \[aq]s/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g\[aq] | ...-.EE-.RE-.IP \[bu] 2-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-\f[CR]delete\f[R] or \f[CR]truncate\f[R] SQL statements) or drop tables-completely as otherwise your postings will be duped.-.SS Commodity styles-When displaying amounts, hledger infers a standard display style for-each commodity/currency, as described below in Commodity display style.-.PP-If needed, this can be overridden by a-\f[CR]\-c/\-\-commodity\-style\f[R] option (except for cost amounts and-amounts displayed by the \f[CR]print\f[R] command, which are always-displayed with all decimal digits).-For example, the following will force dollar amounts to be displayed as-shown:-.IP-.EX-$ hledger print \-c \[aq]$1.000,0\[aq]-.EE-.PP-This option can repeated to set the display style for multiple-commodities/currencies.-Its argument is as described in the commodity directive.-.PP-In some cases hledger will adjust number formatting to improve their-parseability (such as adding trailing decimal marks when needed).-.SS Colour-In terminal output, some commands can produce colour when the terminal-supports it:-.IP \[bu] 2-if the \f[CR]\-\-color/\-\-colour\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]), colour will (or will not) be used;-.IP \[bu] 2-otherwise, if the \f[CR]NO_COLOR\f[R] environment variable is set,-colour will not be used;-.IP \[bu] 2-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.-.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-\f[CR]less\f[R], or \f[CR]more\f[R].-(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,-.IP \[bu] 2-when listing commands, with \f[CR]hledger\f[R]-.IP \[bu] 2-when showing help with \f[CR]hledger [CMD] \-\-help\f[R],-.IP \[bu] 2-when viewing manuals with \f[CR]hledger help\f[R] or-\f[CR]hledger \-\-man\f[R].-.PP-Note the pager is expected to handle ANSI codes, which hledger uses eg-for bold emphasis.-For the common pager \f[CR]less\f[R] (and its \f[CR]more\f[R]-compatibility mode), we add \f[CR]R\f[R] to the \f[CR]LESS\f[R] and-\f[CR]MORE\f[R] 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 \f[CR]NO_COLOR\f[R] environment variable to 1-to disable all ANSI output (see Colour).-.SS Debug output-We intend hledger to be relatively easy to troubleshoot, introspect and-develop.-You can add \f[CR]\-\-debug[=N]\f[R] 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-\f[CR]\-o/\-\-output\-file\f[R] (unless you redirect stderr to stdout,-eg: \f[CR]2>&1\f[R]).-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:-.IP-.EX-hledger bal \-\-debug=3 2>hledger.log-.EE-.SH Environment-These environment variables affect hledger:-.PP-\f[B]COLUMNS\f[R] This is normally set by your terminal; some hledger-commands (\f[CR]register\f[R]) will format their output to this width.-If not set, they will try to use the available terminal width.-.PP-\f[B]LEDGER_FILE\f[R] The main journal file to use when not specified-with \f[CR]\-f/\-\-file\f[R].-Default: \f[CR]$HOME/.hledger.journal\f[R].-.PP-\f[B]NO_COLOR\f[R] If this environment variable is set (with any value),-hledger will not use ANSI color codes in terminal output, unless-overridden by an explicit \f[CR]\-\-color/\-\-colour\f[R] option.-.SH PART 2: DATA FORMATS-.SH Journal-hledger\[aq]s usual data source is a plain text file containing journal-entries in hledger \f[CR]journal\f[R] format.-If you\[aq]re looking for a quick reference, jump ahead to the journal-cheatsheet (or use the table of contents at-https://hledger.org/hledger.html).-.PP-This file represents an accounting General Journal.-The \f[CR].journal\f[R] 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.-.PP-hledger\[aq]s journal format is compatible with most of Ledger\[aq]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.-.PP-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.-.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,-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.-.PP-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\[aq]s data model.-Here\[aq]s a quick cheatsheet/overview, followed by detailed-descriptions of each part.-.SS Journal cheatsheet-.IP-.EX-# Here is the main syntax of hledger\[aq]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 \[dq]comment\[dq] / \[dq]end comment\[dq].-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\[aq]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 \[dq]type\[dq] 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\[aq]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 \[dq]periodic transaction\[dq], for budget/forecast reports-\[ti] 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\[aq]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\[aq]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\[aq]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 \[dq]pending\[dq] or \[dq]cleared\[dq].-    ; There can be a parenthesised (code) after the date/status.-                                    ; Amounts\[aq] 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\[aq]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 \[dq]Chocolate Frogs\[dq]  ; Complex commodity symbols-    assets:pouch             3 \[dq]Chocolate Frogs\[dq]  ; 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 \[at] $1.50  ; \[at]  means per\-unit cost-    assets:investments:2024\-01\-15\-02  3.0 AAAA \[at]\[at] $4    ; \[at]\[at] means total cost-                      ; \[ha] 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 \[dq]Chocolate Frogs\[dq] =      3 \[dq]Chocolate Frogs\[dq]-    assets:investments:2024\-01\-15      0.0 AAAA            =      2.0 AAAA \[at]  $1.50-    assets:investments:2024\-01\-15\-02   0.0 AAAA            =      3.0 AAAA \[at]\[at] $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-.EE-.SS Comments-Lines in the journal will be ignored if they begin with a hash-(\f[CR]#\f[R]) or a semicolon (\f[CR];\f[R]).-(See also Other syntax.)-hledger will also ignore regions beginning with a \f[CR]comment\f[R]-line and ending with an \f[CR]end comment\f[R] line (or file end).-Here\[aq]s a suggestion for choosing between them:-.IP \[bu] 2-\f[CR]#\f[R] for top\-level notes-.IP \[bu] 2-\f[CR];\f[R] for commenting out things temporarily-.IP \[bu] 2-\f[CR]comment\f[R] for quickly commenting large regions (remember-it\[aq]s there, or you might get confused)-.PP-Eg:-.IP-.EX-# a comment line-; another commentline-comment-A multi\-line comment block,-continuing until \[dq]end comment\[dq] directive-or the end of the current file.-end comment-.EE-.PP-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.-.SS 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.-.PP-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:-.IP \[bu] 2-a status character (empty, \f[CR]!\f[R], or \f[CR]*\f[R])-.IP \[bu] 2-a code (any short number or text, enclosed in parentheses)-.IP \[bu] 2-a description (any remaining text until end of line or a semicolon)-.IP \[bu] 2-a comment (any remaining text following a semicolon until end of line,-and any following indented lines beginning with a semicolon)-.IP \[bu] 2-0 or more indented \f[I]posting\f[R] lines, describing what was-transferred and the accounts involved (indented comment lines are also-allowed, but not blank lines or non\-indented lines).-.PP-Here\[aq]s a simple journal file containing one transaction:-.IP-.EX-2008/01/01 income-  assets:bank:checking   $1-  income:salary         $\-1-.EE-.SS Dates-.SS Simple dates-Dates in the journal file use \f[I]simple dates\f[R] format:-\f[CR]YYYY\-MM\-DD\f[R] or \f[CR]YYYY/MM/DD\f[R] or-\f[CR]YYYY.MM.DD\f[R], 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-\f[CR]Y\f[R] directive, or the current date when the command is run.-Some examples: \f[CR]2010\-01\-31\f[R], \f[CR]2010/01/31\f[R],-\f[CR]2010.1.31\f[R], \f[CR]1/31\f[R].-.PP-(The UI also accepts simple dates, as well as the more flexible smart-dates documented in the hledger manual.)-.SS 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 \f[CR]date:DATE\f[R].-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:-.IP-.EX-2015/5/30-    expenses:food     $10  ; food purchased on saturday 5/30-    assets:checking        ; bank cleared it on monday, date:6/1-.EE-.IP-.EX-$ hledger \-f t.j register food-2015\-05\-30                      expenses:food                  $10           $10-.EE-.IP-.EX-$ hledger \-f t.j register checking-2015\-06\-01                      assets:checking               $\-10          $\-10-.EE-.PP-DATE should be a simple date; if the year is not specified it will use-the year of the transaction\[aq]s date.-.PD 0-.P-.PD-The \f[CR]date:\f[R] tag must have a valid simple date value if it is-present, eg a \f[CR]date:\f[R] tag with no value is not allowed.-.SS 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:-.PP-.TS-tab(@);-l l.-T{-mark \ -T}@T{-status-T}-_-T{-\ -T}@T{-unmarked-T}-T{-\f[CR]!\f[R]-T}@T{-pending-T}-T{-\f[CR]*\f[R]-T}@T{-cleared-T}-.TE-.PP-When reporting, you can filter by status with the-\f[CR]\-U/\-\-unmarked\f[R], \f[CR]\-P/\-\-pending\f[R], and-\f[CR]\-C/\-\-cleared\f[R] flags (and you can combine these, eg-\f[CR]\-UP\f[R] to match all except cleared things).-Or you can use the \f[CR]status:\f[R], \f[CR]status:!\f[R], and-\f[CR]status:*\f[R] queries, or the U, P, C keys in hledger\-ui.-.PP-(Note: in Ledger the \[dq]unmarked\[dq] state is called-\[dq]uncleared\[dq]; in hledger we renamed it to \[dq]unmarked\[dq] for-semantic clarity.)-.PP-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.-.PP-What \[dq]uncleared\[dq], \[dq]pending\[dq], and \[dq]cleared\[dq]-actually mean is up to you.-Here\[aq]s one suggestion:-.PP-.TS-tab(@);-lw(9.7n) lw(60.3n).-T{-status-T}@T{-meaning-T}-_-T{-uncleared-T}@T{-recorded but not yet reconciled; needs review-T}-T{-pending-T}@T{-tentatively reconciled (if needed, eg during a big reconciliation)-T}-T{-cleared-T}@T{-complete, reconciled as far as possible, and considered correct-T}-.TE-.PP-With this scheme, you would use \f[CR]\-PC\f[R] to see the current-balance at your bank, \f[CR]\-U\f[R] 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.-.SS Code-After the status mark, but before the description, you can optionally-write a transaction \[dq]code\[dq], enclosed in parentheses.-This is a good place to record a check number, or some other important-transaction id or reference number.-.SS Description-After the date, status mark and/or code fields, the rest of the line (or-until a comment is begun with \f[CR];\f[R]) is the transaction\[aq]s-description.-Here you can describe the transaction (called the \[dq]narration\[dq] in-traditional bookkeeping), or you can record a payee/payer name, or you-can leave it empty.-.PP-Transaction descriptions show up in print output and in register-reports, and can be listed with the descriptions command.-.PP-You can query by description with \f[CR]desc:DESCREGEX\f[R], or pivot on-description with \f[CR]\-\-pivot desc\f[R].-.SS 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 \f[CR]|\f[R] (pipe) character in the-description.-This divides it into a \[dq]payee\[dq] field on the left, and a-\[dq]note\[dq] field on the right.-(Either can be empty.)-.PP-You can query these with \f[CR]payee:PAYEEREGEX\f[R] and-\f[CR]note:NOTEREGEX\f[R], list their values with the payees and notes-commands, or pivot on \f[CR]payee\f[R] or \f[CR]note\f[R].-.PP-Note: in transactions with no \f[CR]|\f[R] character, description,-payee, and note all have the same value.-Once a \f[CR]|\f[R] is added, they become distinct.-(If you\[aq]d like to change this behaviour, please propose it on the-mail list.)-.PP-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\[aq]ll need to ensure every-transaction description contains a \f[CR]|\f[R] and therefore a-checkable payee name, even if it\[aq]s empty.)-.SS Transaction comments-Text following \f[CR];\f[R], after a transaction description, and/or on-indented lines immediately below it, form comments for that transaction.-They are reproduced by \f[CR]print\f[R] but otherwise ignored, except-they may contain tags, which are not ignored.-.IP-.EX-2012\-01\-01 something  ; a transaction comment-    ; a second line of transaction comment-    expenses   1-    assets-.EE-.SS 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:-.IP \[bu] 2-(optional) a status character (empty, \f[CR]!\f[R], or \f[CR]*\f[R]),-followed by a space-.IP \[bu] 2-(required) an account name (any text, optionally containing \f[B]single-spaces\f[R], until end of line or a double space)-.IP \[bu] 2-(optional) \f[B]two or more spaces\f[R] (or tabs) followed by an amount.-.PP-If the amount is positive, it is being added to the account; if-negative, it is being removed from the account.-.PP-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 \[dq]sum up to-zero\[dq] in Transaction balancing below.)-.PP-As a convenience, you can optionally leave one amount blank; hledger-will infer what it should be so as to balance the transaction.-.SS 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.-.PP-You don\[aq]t need to remember that, but if you would like to \- eg for-helping newcomers or for talking with your accountant \- here\[aq]s a-handy mnemonic:-.PP-\f[I]\f[CI]debit  / plus  / left  / short  words\f[I]\f[R]-.PD 0-.P-.PD-\f[I]\f[CI]credit / minus / right / longer words\f[I]\f[R]-.SS 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 \f[B]two or more-spaces\f[R] (or tabs).-It\[aq]s easy to forget at first.-If you ever see the amount being treated as part of the account name,-you\[aq]ll know you probably need to add another space between them.-.SS 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 \[dq]money-borrowed from Frank\[dq] or \[dq]money spent on electricity\[dq].-.PP-You can use any account names you like, but we usually start with the-traditional accounting categories, which in english are-\f[CR]assets\f[R], \f[CR]liabilities\f[R], \f[CR]equity\f[R],-\f[CR]revenues\f[R], \f[CR]expenses\f[R].-(You might see these referred to as A, L, E, R, X for short.)-.PP-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 \f[CR]assets:bank:checking\f[R] and-\f[CR]expenses:food\f[R], hledger will infer this hierarchy of five-accounts:-.IP-.EX-assets-assets:bank-assets:bank:checking-expenses-expenses:food-.EE-.PP-Shown as an outline, the hierarchical tree structure is more clear:-.IP-.EX-assets- bank-  checking-expenses- food-.EE-.PP-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.-.PP-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 \f[B]two or more spaces\f[R] (or tabs).-.PP-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.-.PP-Account names can be altered temporarily or permanently by account-aliases.-.SS Amounts-After the account name, there is usually an amount.-(Remember: between account name and amount, there must be two or more-spaces.)-.PP-hledger\[aq]s amount format is flexible, supporting several-international formats.-Here are some examples.-Amounts have a number (the \[dq]quantity\[dq]):-.IP-.EX-1-.EE-.PP-\&..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:-.IP-.EX-$1-4000 AAPL-3 \[dq]green apples\[dq]-.EE-.PP-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:-.IP-.EX-\-$1-$\-1-.EE-.PP-One or more spaces between the sign and the number are acceptable when-parsing (but they won\[aq]t be displayed in output):-.IP-.EX-+ $1-$\-      1-.EE-.PP-Scientific E notation is allowed:-.IP-.EX-1E\-6-EUR 1E3-.EE-.PP-.SS Decimal marks-A \f[I]decimal mark\f[R] can be written as a period or a comma:-.IP-.EX-1.23-1,23-.EE-.PP-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 \f[CR]1,000\f[R] or-\f[CR]1.000\f[R] 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.-.PP-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 \f[CR]decimal\-mark\f[R] directive at the top-of each data file, like this:-.IP-.EX-decimal\-mark .-.EE-.PP-Or you can declare it per commodity with \f[CR]commodity\f[R]-directives, described below.-.PP-hledger also accepts numbers like \f[CR]10.\f[R] with no digits after-the decimal mark (and will sometimes display numbers that way to-disambiguate them \- see Trailing decimal marks).-.SS 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 \f[I]digit group-mark\f[R] \- 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:-.IP-.EX-     $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-.EE-.SS Commodity-Amounts in hledger have both a \[dq]quantity\[dq], which is a signed-decimal number, and a \[dq]commodity\[dq], which is a currency symbol,-stock ticker, or any word or phrase describing something you are-tracking.-.PP-If the commodity name contains non\-letters (spaces, numbers, or-punctuation), you must always write it inside double quotes-(\f[CR]\[dq]green apples\[dq]\f[R], \f[CR]\[dq]ABC123\[dq]\f[R]).-.PP-If you write just a bare number, that too will have a commodity, with-name \f[CR]\[dq]\[dq]\f[R]; we call that the \[dq]no\-symbol-commodity\[dq].-.PP-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:-\f[CR]1 USD, 2 EUR, 3.456 TSLA\f[R].-In practice, you will only see multi\-commodity amounts in hledger\[aq]s-output; you can\[aq]t write them directly in the journal file.-\-.PP-By default, the format of amounts in the journal influences how hledger-displays them in output.-This is explained in Commodity display style below.-.PP-.SS Costs-After a posting amount, you can note its cost (when buying) or selling-price (when selling) in another commodity, by writing either-\f[CR]\[at] UNITPRICE\f[R] or \f[CR]\[at]\[at] TOTALPRICE\f[R] after it.-This indicates a conversion transaction, where one commodity is-exchanged for another.-.PP-(You might also see this called \[dq]transaction price\[dq] 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 \[dq]cost\[dq], with the understanding that the transaction-could be a purchase or a sale.)-.PP-Costs are usually written explicitly with \f[CR]\[at]\f[R] or-\f[CR]\[at]\[at]\f[R], 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.-.PP-As an example, here are several ways to record purchases of a foreign-currency in hledger, using the cost notation either explicitly or-implicitly:-.IP "1." 3-Write the price per unit, as \f[CR]\[at] UNITPRICE\f[R] after the-amount:-.RS 4-.IP-.EX-2009/1/1-  assets:euros     €100 \[at] $1.35  ; one hundred euros purchased at $1.35 each-  assets:dollars                 ; balancing amount is \-$135.00-.EE-.RE-.IP "2." 3-Write the total price, as \f[CR]\[at]\[at] TOTALPRICE\f[R] after the-amount:-.RS 4-.IP-.EX-2009/1/1-  assets:euros     €100 \[at]\[at] $135  ; one hundred euros purchased at $135 for the lot-  assets:dollars-.EE-.RE-.IP "3." 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 \f[CR]€100 \[at]\[at] $135\f[R], as in example 2:-.RS 4-.IP-.EX-2009/1/1-  assets:euros     €100          ; one hundred euros purchased-  assets:dollars  $\-135          ; for $135-.EE-.RE-.PP-Amounts can be converted to cost at report time using the-\f[CR]\-B/\-\-cost\f[R] flag; this is discussed more in the Cost-reporting section.-.PP-Note that the cost normally should be a positive amount, though it\[aq]s-not required to be.-This can be a little confusing, see discussion at-\-\-infer\-market\-prices: market prices from transactions.-.SS Balance assertions-hledger supports Ledger\-style balance assertions in journal files.-These look like, for example, \f[CR]= EXPECTEDBALANCE\f[R] following a-posting\[aq]s amount.-Eg here we assert the expected dollar balance in accounts a and b after-each posting:-.IP-.EX-2013/1/1-  a   $1 =  $1-  b      = $\-1--2013/1/2-  a   $1 =  $2-  b  $\-1 = $\-2-.EE-.PP-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-\f[CR]\-I/\-\-ignore\-assertions\f[R] flag, which can be useful for-troubleshooting or for reading Ledger files.-(Note: this flag currently does not disable balance assignments,-described below).-.SS Assertions and ordering-hledger calculates and checks an account\[aq]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.-.PP-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.-.SS Assertions and multiple included files-Multiple files included with the \f[CR]include\f[R] 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.-.PP-And if you have multiple postings to an account on the same day, split-across multiple files, and you want to assert the account\[aq]s balance-on that day, you\[aq]ll need to put the assertion in the right file \--the last one in the sequence, probably.-.SS Assertions and multiple \-f files-Unlike \f[CR]include\f[R], when multiple files are specified on the-command line with multiple \f[CR]\-f/\-\-file\f[R] 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.-.PP-If you do want assertions to see balance from earlier files, use-\f[CR]include\f[R], or concatenate the files temporarily.-.SS Assertions and costs-Balance assertions ignore costs, and should normally be written without-one:-.IP-.EX-2019/1/1-  (a)     $1 \[at] €1 = $1-.EE-.PP-We do allow costs to be written in balance assertion amounts, however,-and print shows them, but they don\[aq]t affect whether the assertion-passes or fails.-This is for backward compatibility (hledger\[aq]s close command used to-generate balance assertions with costs), and because balance-\f[I]assignments\f[R] do use costs (see below).-.SS Assertions and commodities-The balance assertions described so far are \[dq]\f[B]single commodity-balance assertions\f[R]\[dq]: 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.-.PP-If an account contains multiple commodities, you can assert their-balances by writing multiple postings with balance assertions, one for-each commodity:-.IP-.EX-2013/1/1-  usd   $\-1-  eur   €\-1-  both--2013/1/2-  both    0 = $1-  both    0 = €1-.EE-.PP-In hledger you can make a stronger \[dq]\f[B]sole commodity balance-assertion\f[R]\[dq] by writing two equals signs-(\f[CR]== EXPECTEDBALANCE\f[R]).-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):-.IP-.EX-2013/1/1-  usd   $\-1  == $\-1  ; these sole commodity assertions succeed-  eur   €\-1  == €\-1-  both      ;==  $1  ; this one would fail because \[aq]both\[aq] contains $ and €-.EE-.PP-It\[aq]s less easy to make a \[dq]\f[B]sole commodities balance-assertion\f[R]\[dq] (note the plural) \- ie, asserting that an account-contains two or more specified commodities and no others.-It can be done by-.IP "1." 3-isolating each commodity in a subaccount, and asserting those-.IP "2." 3-and also asserting there are no commodities in the parent account-itself:-.IP-.EX-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-.EE-.SS Assertions and subaccounts-All of the balance assertions above (both \f[CR]=\f[R] and-\f[CR]==\f[R]) are \[dq]\f[B]subaccount\-exclusive balance-assertions\f[R]\[dq]; they ignore any balances that exist in deeper-subaccounts.-.PP-In hledger you can make \[dq]\f[B]subaccount\-inclusive balance-assertions\f[R]\[dq] by adding a star after the equals (\f[CR]=*\f[R] or-\f[CR]==*\f[R]):-.IP-.EX-2019/1/1-  equity:start-  assets:checking  $10-  assets:savings   $10-  assets            $0 ==* $20  ; assets + subaccounts contains $20 and nothing else-.EE-.SS Assertions and virtual postings-Balance assertions always consider both real and virtual postings; they-are not affected by the \f[CR]\-\-real/\-R\f[R] flag or \f[CR]real:\f[R]-query.-.SS Assertions and auto postings-Balance assertions \f[I]are\f[R] affected by the \f[CR]\-\-auto\f[R]-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:-.IP \[bu] 2-assert the balance calculated with \f[CR]\-\-auto\f[R], and always use-\f[CR]\-\-auto\f[R] with that file-.IP \[bu] 2-or assert the balance calculated without \f[CR]\-\-auto\f[R], and never-use \f[CR]\-\-auto\f[R] with that file-.IP \[bu] 2-or avoid balance assertions on accounts affected by auto postings (or-avoid auto postings entirely).-.SS 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.-.SS Posting comments-Text following \f[CR];\f[R], at the end of a posting line, and/or on-indented lines immediately below it, form comments for that posting.-They are reproduced by \f[CR]print\f[R] but otherwise ignored, except-they may contain tags, which are not ignored.-.IP-.EX-2012\-01\-01-    expenses   1  ; a comment for posting 1-    assets-    ; a comment for posting 2-    ; a second comment line for posting 2-.EE-.SS 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\[aq] sum perfectly with pencil and paper, hledger should-agree with you.-.PP-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 ?-.PP-hledger currently decides it based on the commodity display styles: if-the postings\[aq] sum would appear to be zero when displayed with the-standard display precisions, the transaction is considered balanced.-.PP-Or equivalently: if the journal entry is displayed with amounts rounded-to the standard display precisions (with-\f[CR]hledger print \-\-round=hard\f[R]), and a human with pencil and-paper would agree that those displayed amounts add up to zero, the-transaction is considered balanced.-.PP-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-\f[CR]\-c/\-\-commodity\-style\f[R] 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).-.PP-Other PTA tools (Ledger, Beancount..)-have their own ways of doing it.-Possible improvements are discussed at #1964.-.PP-Note: if you have multiple journal files, and are relying on commodity-directives to make imprecise journal entries balance, the-directives\[aq] placement might be important \- see \f[CR]commodity\f[R]-directive.-.SS 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.-.PP-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: \f[CR]2024\-01\-01 a transaction   ; foo:\f[R] Note this is an-exception to the usual rule that things in comments are ignored.-.PP-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).-.PP-For example, here are five different tags: one on the-\f[CR]assets:checking\f[R] account, two on the transaction, and two on-the \f[CR]expenses:food\f[R] posting:-.IP-.EX-account assets:checking         ; accounttag:--2017/1/16 bought groceries      ; transactiontag\-1:-    ; transactiontag\-2:-    assets:checking        $\-1-    expenses:food           $1  ; postingtag:, another\-posting\-tag:-.EE-.PP-Postings also inherit tags from their transaction and their account.-And transactions also acquire tags from their postings (and-postings\[aq] 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).-.SS Tag names-Most non\-whitespace characters are allowed in tag names.-Eg \f[CR]😀:\f[R] is a valid tag.-.PP-You can list the tag names used in your journal with the tags command:-.PD 0-.P-.PD-\f[CR]hledger tags [NAMEREGEX]\f[R]-.PP-In commands which use a query, you can match by tag name.-Eg:-.PD 0-.P-.PD-\f[CR]hledger print tag:NAMEREGEX\f[R]-.PP-You can declare valid tag names with the tag directive and then check-them with the check command.-.SS Special tags-Some tag names have special significance to hledger.-There\[aq]s not much harm in using them yourself, but some could produce-an error message, particularly the \f[CR]date:\f[R] and \f[CR]type:\f[R]-tags.-They are explained elsewhere, but here is a quick list for reference:-.PP-Tags you can set to influence hledger\[aq]s behaviour:-.IP-.EX- date                   \-\- overrides a posting\[aq]s date- date2                  \-\- overrides a posting\[aq]s secondary date- type                   \-\- declares an account\[aq]s type-.EE-.PP-Tags hledger adds to indicate generated data:-.IP-.EX- 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)-.EE-.PP-Tags hledger uses internally:-.IP-.EX- _conversion\-matched    \-\- exists on postings which have been matched with a nearby \[at]/\[at]\[at] cost annotation-.EE-.SS 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.-.PP-Eg in the following posting, the three tags\[aq] values are \[dq]value-1\[dq], \[dq]value 2\[dq], and \[dq]\[dq] (empty) respectively:-.IP-.EX-    expenses:food   $10    ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz-.EE-.PP-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\[aq]s value or remove a-tag.-.PP-You can list all the values used for a particular tag in the journal-with-.PD 0-.P-.PD-\f[CR]hledger tags TAGNAME \-\-values\f[R]-.PP-You can match on tag values with a query like-\f[CR]tag:NAMEREGEX=VALUEREGEX\f[R]-.SS Directives-Besides transactions, there is something else you can put in a-\f[CR]journal\f[R] file: directives.-These are declarations, beginning with a keyword, that modify-hledger\[aq]s behaviour.-Some directives can have more specific subdirectives, indented below-them.-hledger\[aq]s directives are similar to Ledger\[aq]s in many cases, but-there are also many differences.-Directives are not required, but can be useful.-Here are the main directives:-.PP-.TS-tab(@);-lw(39.7n) lw(30.3n).-T{-purpose-T}@T{-directive-T}-_-T{-\f[B]READING DATA:\f[R]-T}@T{-T}-T{-Rewrite account names-T}@T{-\f[CR]alias\f[R]-T}-T{-Comment out sections of the file-T}@T{-\f[CR]comment\f[R]-T}-T{-Declare file\[aq]s decimal mark, to help parse amounts accurately-T}@T{-\f[CR]decimal\-mark\f[R]-T}-T{-Include other data files-T}@T{-\f[CR]include\f[R]-T}-T{-\f[B]GENERATING DATA:\f[R]-T}@T{-T}-T{-Generate recurring transactions or budget goals-T}@T{-\f[CR]\[ti]\f[R]-T}-T{-Generate extra postings on existing transactions-T}@T{-\f[CR]=\f[R]-T}-T{-\f[B]CHECKING FOR ERRORS:\f[R]-T}@T{-T}-T{-Define valid entities to provide more error checking-T}@T{-\f[CR]account\f[R], \f[CR]commodity\f[R], \f[CR]payee\f[R],-\f[CR]tag\f[R]-T}-T{-\f[B]REPORTING:\f[R]-T}@T{-T}-T{-Declare accounts\[aq] type and display order-T}@T{-\f[CR]account\f[R]-T}-T{-Declare commodity display styles-T}@T{-\f[CR]commodity\f[R]-T}-T{-Declare market prices-T}@T{-\f[CR]P\f[R]-T}-.TE-.SS 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, \f[CR]alias\f[R] directives do not affect parent or sibling-files.-But there are usually workarounds; for example, put \f[CR]alias\f[R]-directives in your top\-most file, before including other files.-.PP-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.-.SS Directive effects-Here are all hledger\[aq]s directives, with their effects and scope-summarised \- nine main directives, plus four others which we consider-non\-essential:-.PP-.TS-tab(@);-lw(3.5n) lw(64.1n) lw(2.4n).-T{-directive-T}@T{-what it does-T}@T{-ends at file end?-T}-_-T{-\f[B]\f[CB]account\f[B]\f[R]-T}@T{-Declares an account, for checking all entries in all files; and its-display order and type.-Subdirectives: any text, ignored.-T}@T{-N-T}-T{-\f[B]\f[CB]alias\f[B]\f[R]-T}@T{-Rewrites account names, in following entries until end of current file-or \f[CR]end aliases\f[R].-Command line equivalent: \f[CR]\-\-alias\f[R]-T}@T{-Y-T}-T{-\f[B]\f[CB]comment\f[B]\f[R]-T}@T{-Ignores part of the journal file, until end of current file or-\f[CR]end comment\f[R].-T}@T{-Y-T}-T{-\f[B]\f[CB]commodity\f[B]\f[R]-T}@T{-Declares up to four things: 1.-a commodity symbol, for checking 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 \f[CR]decimal\-mark\f[R]-directive 4.-the precision to use for balanced\-transaction checking in this-commodity, in this file and its children.-\ Takes precedence over \f[CR]D\f[R].-Subdirectives: \f[CR]format\f[R] (ignored).-Command line equivalent: \f[CR]\-c/\-\-commodity\-style\f[R]-T}@T{-N,N,Y,Y-T}-T{-\f[B]\f[CB]decimal\-mark\f[B]\f[R]-T}@T{-Declares the decimal mark, for parsing amounts of all commodities in-following entries until next \f[CR]decimal\-mark\f[R] or end of current-file.-Included files can override.-Takes precedence over \f[CR]commodity\f[R] and \f[CR]D\f[R].-T}@T{-Y-T}-T{-\f[B]\f[CB]include\f[B]\f[R]-T}@T{-Includes entries and directives from another file, as if they were-written inline.-Command line alternative: multiple \f[CR]\-f/\-\-file\f[R]-T}@T{-N-T}-T{-\f[B]\f[CB]payee\f[B]\f[R]-T}@T{-Declares a payee name, for checking all entries in all files.-T}@T{-N-T}-T{-\f[B]\f[CB]P\f[B]\f[R]-T}@T{-Declares the market price of a commodity on some date, for value-reports.-T}@T{-N-T}-T{-\f[B]\f[CB]\[ti]\f[B]\f[R] (tilde)-T}@T{-Declares a periodic transaction rule that generates future transactions-with \f[CR]\-\-forecast\f[R] and budget goals with-\f[CR]balance \-\-budget\f[R].-T}@T{-N-T}-T{-Other syntax:-T}@T{-T}@T{-T}-T{-\f[B]\f[CB]apply account\f[B]\f[R]-T}@T{-Prepends a common parent account to all account names, in following-entries until end of current file or \f[CR]end apply account\f[R].-T}@T{-Y-T}-T{-\f[B]\f[CB]D\f[B]\f[R]-T}@T{-Sets a default commodity to use for no\-symbol amounts;and, if there is-no \f[CR]commodity\f[R] directive for this commodity: its decimal mark,-balancing precision, and display style, as above.-T}@T{-Y,Y,N,N-T}-T{-\f[B]\f[CB]Y\f[B]\f[R]-T}@T{-Sets a default year to use for any yearless dates, in following entries-until end of current file.-T}@T{-Y-T}-T{-\f[B]\f[CB]=\f[B]\f[R] (equals)-T}@T{-Declares an auto posting rule that generates extra postings on matched-transactions with \f[CR]\-\-auto\f[R], in current, parent, and child-files (but not sibling files, see #1212).-T}@T{-partly-T}-T{-\f[B]Other Ledger directives\f[R]-T}@T{-Other directives from Ledger\[aq]s file format are accepted but ignored.-T}@T{-T}-.TE-.SS \f[CR]account\f[R] directive-\f[CR]account\f[R] 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:-.IP \[bu] 2-They can document your intended chart of accounts, providing a-reference.-.IP \[bu] 2-They can store additional account information as comments, or as tags-which can be used to filter or pivot reports.-.IP \[bu] 2-They can restrict which accounts may be posted to by transactions, eg in-strict mode, which helps prevent errors.-.IP \[bu] 2-They influence account display order in reports, allowing-non\-alphabetic sorting (eg Revenues to appear above Expenses).-.IP \[bu] 2-They can help hledger know your accounts\[aq] types (asset, liability,-equity, revenue, expense), enabling reports like balancesheet and-incomestatement.-.IP \[bu] 2-They help with account name completion (in hledger add, hledger\-web,-hledger\-iadd, ledger\-mode, etc.)-.PP-They are written as the word \f[CR]account\f[R] followed by a-hledger\-style account name.-Eg:-.IP-.EX-account assets:bank:checking-.EE-.PP-Ledger\-style indented subdirectives are also accepted, but ignored:-.IP-.EX-account assets:bank:checking-  format subdirective  ; currently ignored-.EE-.SS Account comments-Text following \f[B]two or more spaces\f[R] and \f[CR];\f[R] at the end-of an account directive line, and/or following \f[CR];\f[R] on indented-lines immediately below it, form comments for that account.-They are ignored except they may contain tags, which are not ignored.-.PP-The two\-space requirement for same\-line account comments is because-\f[CR];\f[R] is allowed in account names.-.IP-.EX-account assets:bank:checking    ; same\-line comment, at least 2 spaces before the semicolon-  ; next\-line comment-  ; some tags \- type:A, acctnum:12345-.EE-.SS 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\[aq]t warn you when you-mis\-spell an account name in the journal.-Usually you\[aq]ll find that error later, as an extra account in balance-reports, or an incorrect balance when reconciling.-.PP-In strict mode, enabled with the \f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R]-flag, hledger will report an error if any transaction uses an account-name that has not been declared by an account directive.-Some notes:-.IP \[bu] 2-The declaration is case\-sensitive; transactions must use the correct-account name capitalisation.-.IP \[bu] 2-The account directive\[aq]s scope is \[dq]whole file and below\[dq] (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\[aq]s usual to put them at the top.-.IP \[bu] 2-Accounts can only be declared in \f[CR]journal\f[R] files, but will-affect included files of all types.-.IP \[bu] 2-It\[aq]s currently not possible to declare \[dq]all possible-subaccounts\[dq] with a wildcard; every account posted to must be-declared.-.SS 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:-.IP-.EX-account assets-account liabilities-account equity-account revenues-account expenses-.EE-.PP-Now hledger displays them in that order:-.IP-.EX-$ hledger accounts-assets-liabilities-equity-revenues-expenses-.EE-.PP-If there are undeclared accounts, those will be displayed last, in-alphabetical order.-.PP-Sorting is done within each group of sibling accounts, at each level of-the account tree.-Eg, a declaration like \f[CR]account parent:child\f[R] influences-\f[CR]child\f[R]\[aq]s position among its siblings.-.PP-Note, it does not affect \f[CR]parent\f[R]\[aq]s position; for that, you-need an \f[CR]account parent\f[R] declaration.-.PP-Sibling accounts are always displayed together; hledger won\[aq]t-display \f[CR]x:y\f[R] in between \f[CR]a:b\f[R] and \f[CR]a:c\f[R].-.PP-An account directive both declares an account as a valid posting target,-and declares its display order; you can\[aq]t easily do one without the-other.-.SS 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 \f[CR]type:\f[R] query.-.PP-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\[aq]s more robust to declare accounts\[aq] types explicitly, by-adding \f[CR]type:\f[R] tags to their account directives.-The tag\[aq]s value should be one of the five main account types:-.IP \[bu] 2-\f[CR]A\f[R] or \f[CR]Asset\f[R] (things you own)-.IP \[bu] 2-\f[CR]L\f[R] or \f[CR]Liability\f[R] (things you owe)-.IP \[bu] 2-\f[CR]E\f[R] or \f[CR]Equity\f[R] (investment/ownership; balanced-counterpart of assets & liabilities)-.IP \[bu] 2-\f[CR]R\f[R] or \f[CR]Revenue\f[R] (what you received money from, AKA-income; technically part of Equity)-.IP \[bu] 2-\f[CR]X\f[R] or \f[CR]Expense\f[R] (what you spend money on; technically-part of Equity)-.PP-or, it can be (these are used less often):-.IP \[bu] 2-\f[CR]C\f[R] or \f[CR]Cash\f[R] (a subtype of Asset, indicating liquid-assets for the cashflow report)-.IP \[bu] 2-\f[CR]V\f[R] or \f[CR]Conversion\f[R] (a subtype of Equity, for-conversions (see Cost reporting).)-.PP-Subaccounts inherit their parent\[aq]s type, or they can override it.-Here is a typical set of account type declarations:-.IP-.EX-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-.EE-.PP-Here are some tips for working with account types.-.IP \[bu] 2-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\[aq]t work for you, just ignore them and declare your account-types.-See also Regular expressions.-.RS 2-.IP-.EX-If account\[aq]s name contains this (CI) regular expression:            | its type is:-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\--\[ha]assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|current)(:|$) | Cash-\[ha]assets?(:|$)                                                       | Asset-\[ha](debts?|liabilit(y|ies))(:|$)                                      | Liability-\[ha]equity:(trad(e|ing)|conversion)s?(:|$)                             | Conversion-\[ha]equity(:|$)                                                        | Equity-\[ha](income|revenue)s?(:|$)                                            | Revenue-\[ha]expenses?(:|$)                                                     | Expense-.EE-.RE-.IP \[bu] 2-If you declare any account types, it\[aq]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.-.IP \[bu] 2-Certain uses of account aliases can disrupt account types.-See Rewriting accounts > Aliases and account types.-.IP \[bu] 2-As mentioned above, subaccounts will inherit a type from their parent-account.-More precisely, an account\[aq]s type is decided by the first of these-that exists:-.RS 2-.IP "1." 3-A \f[CR]type:\f[R] declaration for this account.-.IP "2." 3-A \f[CR]type:\f[R] declaration in the parent accounts above it,-preferring the nearest.-.IP "3." 3-An account type inferred from this account\[aq]s name.-.IP "4." 3-An account type inferred from a parent account\[aq]s name, preferring-the nearest parent.-.IP "5." 3-Otherwise, it will have no type.-.RE-.IP \[bu] 2-For troubleshooting, you can list accounts and their types with:-.RS 2-.IP-.EX-$ hledger accounts \-\-types [ACCTPAT] [\-DEPTH] [type:TYPECODES]-.EE-.RE-.SS \f[CR]alias\f[R] directive-You can define account alias rules which rewrite your account names, or-parts of them, before generating reports.-This can be useful for:-.IP \[bu] 2-expanding shorthand account names to their full form, allowing easier-data entry and a less verbose journal-.IP \[bu] 2-adapting old journals to your current chart of accounts-.IP \[bu] 2-experimenting with new account organisations, like a new hierarchy-.IP \[bu] 2-combining two accounts into one, eg to see their sum or difference on-one line-.IP \[bu] 2-customising reports-.PP-Account aliases also rewrite account names in account directives.-They do not affect account names being entered via hledger add or-hledger\-web.-.PP-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.-.PP-See also Rewrite account names.-.SS Basic aliases-To set an account alias, use the \f[CR]alias\f[R] 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:-.IP-.EX-alias OLD = NEW-.EE-.PP-Or, you can use the \f[CR]\-\-alias \[aq]OLD=NEW\[aq]\f[R] option on the-command line.-This affects all entries.-It\[aq]s useful for trying out aliases interactively.-.PP-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:-.IP-.EX-alias checking = assets:bank:wells fargo:checking-; rewrites \[dq]checking\[dq] to \[dq]assets:bank:wells fargo:checking\[dq], or \[dq]checking:a\[dq] to \[dq]assets:bank:wells fargo:checking:a\[dq]-.EE-.SS 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.)-.PP-Eg:-.IP-.EX-alias /REGEX/ = REPLACEMENT-.EE-.PP-or:-.IP-.EX-$ hledger \-\-alias \[aq]/REGEX/=REPLACEMENT\[aq] ...-.EE-.PP-Any part of an account name matched by REGEX will be replaced by-REPLACEMENT.-REGEX is case\-insensitive as usual.-.PP-If you need to match a forward slash, escape it with a backslash, eg-\f[CR]/\[rs]/=:\f[R].-.PP-If REGEX contains parenthesised match groups, these can be referenced by-the usual backslash and number in REPLACEMENT:-.IP-.EX-alias /\[ha](.+):bank:([\[ha]:]+):(.*)/ = \[rs]1:\[rs]2 \[rs]3-; rewrites \[dq]assets:bank:wells fargo:checking\[dq] to  \[dq]assets:wells fargo checking\[dq]-.EE-.PP-REPLACEMENT continues to the end of line (or on command line, to end of-option argument), so it can contain trailing whitespace.-.SS Combining aliases-You can define as many aliases as you like, using journal directives-and/or command line options.-.PP-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.-.PP-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:-.IP "1." 3-\f[CR]alias\f[R] directives preceding the journal entry, most recently-parsed first (ie, reading upward from the journal entry, bottom to top)-.IP "2." 3-\f[CR]\-\-alias\f[R] options, in the order they appeared on the command-line (left to right).-.PP-In other words, for (an account name in) a given journal entry:-.IP \[bu] 2-the nearest alias declaration before/above the entry is applied first-.IP \[bu] 2-the next alias before/above that will be be applied next, and so on-.IP \[bu] 2-aliases defined after/below the entry do not affect it.-.PP-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.-.PP-In case of trouble, adding \f[CR]\-\-debug=6\f[R] to the command line-will show which aliases are being applied when.-.SS Aliases and multiple files-As explained at Directives and multiple files, \f[CR]alias\f[R]-directives do not affect parent or sibling files.-Eg in this command,-.IP-.EX-hledger \-f a.aliases \-f b.journal-.EE-.PP-account aliases defined in a.aliases will not affect b.journal.-Including the aliases doesn\[aq]t work either:-.IP-.EX-include a.aliases--2023\-01\-01  ; not affected by a.aliases-  foo  1-  bar-.EE-.PP-This means that account aliases should usually be declared at the start-of your top\-most file, like this:-.IP-.EX-alias foo=Foo-alias bar=Bar--2023\-01\-01  ; affected by aliases above-  foo  1-  bar--include c.journal  ; also affected-.EE-.SS \f[CR]end aliases\f[R] directive-You can clear (forget) all currently defined aliases (seen in the-journal so far, or defined on the command line) with this directive:-.IP-.EX-end aliases-.EE-.SS Aliases can generate bad account names-Be aware that account aliases can produce malformed account names, which-could cause confusing reports or invalid \f[CR]print\f[R] output.-For example, you could erase all account names:-.IP-.EX-2021\-01\-01-  a:aa     1-  b-.EE-.IP-.EX-$ hledger print \-\-alias \[aq]/.*/=\[aq]-2021\-01\-01-                   1-.EE-.PP-The above \f[CR]print\f[R] output is not a valid journal.-Or you could insert an illegal double space, causing \f[CR]print\f[R]-output that would give a different journal when reparsed:-.IP-.EX-2021\-01\-01-  old    1-  other-.EE-.IP-.EX-$ hledger print \-\-alias old=\[dq]new  USD\[dq] | hledger \-f\- print-2021\-01\-01-    new             USD 1-    other-.EE-.SS 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.-.PP-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.-.PP-Secondly, if an account\[aq]s type is being inferred from its name,-renaming it by an alias could prevent or alter that.-.PP-If you are using account aliases and the \f[CR]type:\f[R] query is not-matching accounts as you expect, try troubleshooting with the accounts-command, eg something like:-.IP-.EX-$ hledger accounts \-\-alias assets=bassetts type:a-.EE-.SS \f[CR]commodity\f[R] directive-The \f[CR]commodity\f[R] directive performs several functions:-.IP "1." 3-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.-.IP "2." 3-It declares how all amounts in this commodity should be displayed, eg-how many decimals to show.-See Commodity display style above.-.IP "3." 3-(If no \f[CR]decimal\-mark\f[R] 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.-.IP "4." 3-It declares the precision with which this commodity\[aq]s amounts should-be compared when checking for balanced transactions, anywhere in this-file and files it includes, until end of current file.-.PP-Declaring commodities solves several common parsing/display problems, so-we recommend it.-.PP-Note that effects 3 and 4 above end at the end of the directive\[aq]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.-.PP-(Related: #793)-.SS Commodity directive syntax-A commodity directive is normally the word \f[CR]commodity\f[R] followed-by a sample amount (and optionally a comment).-Only the amount\[aq]s symbol and format is significant.-Eg:-.IP-.EX-commodity $1000.00-commodity 1.000,00 EUR-commodity 1 000 000.0000   ; the no\-symbol commodity-.EE-.PP-Commodities do not have tags (tags in the comment will be ignored).-.PP-A commodity directive\[aq]s sample amount must always include a period-or comma decimal mark (this rule helps disambiguate decimal marks and-digit group marks).-If you don\[aq]t want to show any decimal digits, write the decimal mark-at the end:-.IP-.EX-commodity 1000. AAAA       ; show AAAA with no decimals-.EE-.PP-Commodity symbols containing spaces, numbers, or punctuation must be-enclosed in double quotes, as usual:-.IP-.EX-commodity 1.0000 \[dq]AAAA 2023\[dq]-.EE-.PP-Commodity directives normally include a sample amount, but can declare-only a symbol (ie, just function 1 above):-.IP-.EX-commodity $-commodity INR-commodity \[dq]AAAA 2023\[dq]-commodity \[dq]\[dq]               ; the no\-symbol commodity-.EE-.PP-Commodity directives may also be written with an indented-\f[CR]format\f[R] subdirective, as in Ledger.-The symbol is repeated and must be the same in both places.-Other subdirectives are currently ignored:-.IP-.EX-; 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-.EE-.SS Commodity error checking-In strict mode (\f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R]) (or when you run-\f[CR]hledger check commodities\f[R]), 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).-.SS \f[CR]decimal\-mark\f[R] directive-You can use a \f[CR]decimal\-mark\f[R] 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-.IP-.EX-decimal\-mark .-.EE-.PP-or-.IP-.EX-decimal\-mark ,-.EE-.PP-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).-.SS \f[CR]include\f[R] directive-You can pull in the content of additional files by writing an include-directive, like this:-.IP-.EX-include FILEPATH-.EE-.PP-Only journal files can include, and only journal, timeclock or timedot-files can be included (not CSV files, currently).-.PP-If the file path does not begin with a slash, it is relative to the-current file\[aq]s folder.-.PP-A tilde means home directory, eg: \f[CR]include \[ti]/main.journal\f[R].-.PP-The path may contain glob patterns to match multiple files, eg:-\f[CR]include *.journal\f[R].-.PP-There is limited support for recursive wildcards: \f[CR]**/\f[R] (the-slash is required) matches 0 or more subdirectories.-It\[aq]s not super convenient since you have to avoid include cycles and-including directories, but this can be done, eg:-\f[CR]include */**/*.journal\f[R].-.PP-The path may also be prefixed to force a specific file format,-overriding the file extension (as described in Data formats):-\f[CR]include timedot:\[ti]/notes/2023*.md\f[R].-.SS \f[CR]P\f[R] directive-The \f[CR]P\f[R] 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.-.PP-The format is:-.IP-.EX-P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT-.EE-.PP-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:-.IP-.EX-# 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-.EE-.PP-The \f[CR]\-V\f[R], \f[CR]\-X\f[R] and \f[CR]\-\-value\f[R] flags use-these market prices to show amount values in another commodity.-See Value reporting.-.PP-.SS \f[CR]payee\f[R] directive-\f[CR]payee PAYEE NAME\f[R]-.PP-This directive can be used to declare a limited set of payees which may-appear in transaction descriptions.-The \[dq]payees\[dq] check will report an error if any transaction-refers to a payee that has not been declared.-Eg:-.IP-.EX-payee Whole Foods    ; a comment-.EE-.PP-Payees do not have tags (tags in the comment will be ignored).-.PP-To declare the empty payee name, use \f[CR]\[dq]\[dq]\f[R].-.IP-.EX-payee \[dq]\[dq]-.EE-.PP-Ledger\-style indented subdirectives, if any, are currently ignored.-.SS \f[CR]tag\f[R] directive-\f[CR]tag TAGNAME\f[R]-.PP-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:-.IP-.EX-tag  item\-id-.EE-.PP-Any indented subdirectives are currently ignored.-.PP-The \[dq]tags\[dq] 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 .-.SS Periodic transactions-The \f[CR]\[ti]\f[R] directive declares a \[dq]periodic rule\[dq] which-generates temporary extra transactions, usually recurring at some-interval, when hledger is run with the \f[CR]\-\-forecast\f[R] flag.-These \[dq]forecast transactions\[dq] are useful for forecasting future-activity.-They exist only for the duration of the report, and only when-\f[CR]\-\-forecast\f[R] is used; they are not saved in the journal file-by hledger.-.PP-Periodic rules also have a second use: with the \f[CR]\-\-budget\f[R]-flag they set budget goals for budgeting.-.PP-Periodic rules can be a little tricky, so before you use them, read this-whole section, or at least the following tips:-.IP "1." 3-Two spaces accidentally added or omitted will cause you trouble \- read-about this below.-.IP "2." 3-For troubleshooting, show the generated transactions with-\f[CR]hledger print \-\-forecast tag:generated\f[R] or-\f[CR]hledger register \-\-forecast tag:generated\f[R].-.IP "3." 3-Forecasted transactions will begin only after the last non\-forecasted-transaction\[aq]s date.-.IP "4." 3-Forecasted transactions will end 6 months from today, by default.-See below for the exact start/end rules.-.IP "5." 3-period expressions can be tricky.-Their documentation needs improvement, but is worth studying.-.IP "6." 3-Some period expressions with a repeating interval must begin on a-natural boundary of that interval.-Eg in \f[CR]weekly from DATE\f[R], DATE must be a monday.-\f[CR]\[ti] weekly from 2019/10/1\f[R] (a tuesday) will give an error.-.IP "7." 3-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\[aq]s a bit inconsistent with the above.)-Eg:  \f[CR]\[ti] every 10th day of month from 2023/01\f[R], which is-equivalent to  \f[CR]\[ti] every 10th day of month from 2023/01/01\f[R],-will be adjusted to start on 2019/12/10.-.SS Periodic rule syntax-A periodic transaction rule looks like a normal journal entry, with the-date replaced by a tilde (\f[CR]\[ti]\f[R]) followed by a period-expression (mnemonic: \f[CR]\[ti]\f[R] looks like a recurring sine-wave.):-.IP-.EX-# every first of month-\[ti] monthly-    expenses:rent          $2000-    assets:bank:checking--# every 15th of month in 2023\[aq]s first quarter:-\[ti] monthly from 2023\-04\-15 to 2023\-06\-16-    expenses:utilities          $400-    assets:bank:checking-.EE-.PP-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\[aq]-start dates).-.SS Periodic rules and relative dates-Partial or relative dates (like \f[CR]12/31\f[R], \f[CR]25\f[R],-\f[CR]tomorrow\f[R], \f[CR]last week\f[R], \f[CR]next quarter\f[R]) 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:-.IP "1." 3-the first day of the default year specified by a recent \f[CR]Y\f[R]-directive-.IP "2." 3-or the date specified with \f[CR]\-\-today\f[R]-.IP "3." 3-or the date on which you are running the report.-.PP-They will not be affected at all by report period or forecast period-dates.-.SS Two spaces between period expression and description!-If the period expression is followed by a transaction description, these-must be separated by \f[B]two or more spaces\f[R].-This helps hledger know where the period expression ends, so that-descriptions can not accidentally alter their meaning, as in this-example:-.IP-.EX-; 2 or more spaces needed here, so the period is not understood as \[dq]every 2 months in 2023\[dq]-;               ||-;               vv-\[ti] every 2 months  in 2023, we will review-    assets:bank:checking   $1500-    income:acme inc-.EE-.PP-So,-.IP \[bu] 2-Do write two spaces between your period expression and your transaction-description, if any.-.IP \[bu] 2-Don\[aq]t accidentally write two spaces in the middle of your period-expression.-.SS Auto postings-The \f[CR]=\f[R] directive declares an \[dq]auto posting rule\[dq],-which adds extra postings to existing transactions.-(Remember, postings are the account name & amount lines below a-transaction\[aq]s date & description.)-.PP-In the journal, an auto posting rule looks quite like a transaction, but-instead of date and description it has \f[CR]=\f[R] (mnemonic:-\[dq]match\[dq]) and a query, like this:-.IP-.EX-= QUERY-    ACCOUNT    AMOUNT-    ...-.EE-.PP-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.-.PP-Each \f[CR]=\f[R] rule works like this: when hledger is run with the-\f[CR]\-\-auto\f[R] flag, wherever the QUERY matches a posting in the-journal, the rule\[aq]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 \f[CR]\-\-auto\f[R] is used; they-are not saved in the journal file by hledger.-.PP-Generated postings\[aq] amounts can depend on the matched posting\[aq]s-amount.-So auto postings can be useful for, eg, adding tax postings with a-standard percentage.-AMOUNT can be:-.IP \[bu] 2-a number with no commodity symbol, like \f[CR]2\f[R].-The matched posting\[aq]s commodity symbol will be added to this.-.IP \[bu] 2-a normal amount with a commodity symbol, like \f[CR]$2\f[R].-This will be used as\-is.-.IP \[bu] 2-an asterisk followed by a number, like \f[CR]*2\f[R].-This will multiply the matched posting\[aq]s amount (and total price, if-any) by the number.-.IP \[bu] 2-an asterisk followed by an amount with commodity symbol, like-\f[CR]*$2\f[R].-This multiplies and also replaces the commodity symbol with this new-one.-.PP-Some examples:-.IP-.EX-; 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-.EE-.IP-.EX-$ 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-.EE-.PP-Note that depending fully on generated data such as this has some-drawbacks \- it\[aq]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\[aq]t use \f[CR]\-\-auto\f[R]).-An alternative is to use auto postings in \[dq]one time\[dq] fashion \--use them to help build a complex journal entry, view it with-\f[CR]hledger print \-\-auto\f[R], and then copy that output into the-journal file to make it permanent.-.SS 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[CR]\-f\f[R]/\f[CR]\-\-file\f[R] are used \- see #1212).-.SS 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.-.SS Auto postings and transaction balancing / inferred amounts / balance assertions-Currently, auto postings are added:-.IP \[bu] 2-after missing amounts are inferred, and transactions are checked for-balancedness,-.IP \[bu] 2-but before balance assertions are checked.-.PP-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.-.PP-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.-.SS Auto posting tags-Automated postings will have some extra tags:-.IP \[bu] 2-\f[CR]generated\-posting:= QUERY\f[R] \- shows this was generated by an-auto posting rule, and the query-.IP \[bu] 2-\f[CR]_generated\-posting:= QUERY\f[R] \- a hidden tag, which does not-appear in hledger\[aq]s output.-This can be used to match postings generated \[dq]just now\[dq], rather-than generated in the past and saved to the journal.-.PP-Also, any transaction that has been changed by auto posting rules will-have these tags added:-.IP \[bu] 2-\f[CR]modified:\f[R] \- this transaction was modified-.IP \[bu] 2-\f[CR]_modified:\f[R] \- a hidden tag not appearing in the comment; this-transaction was modified \[dq]just now\[dq].-.SS 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-\f[CR]tag:_generated\-transaction\f[R] to their QUERY.-This can be useful when generating new journal entries to be saved in-the journal.-.SS 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.-.SS 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:-.IP-.EX-; 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-.EE-.PP-or when adjusting a balance to reality:-.IP-.EX-; no cash left; update balance, record any untracked spending as a generic expense-2016/1/15-  assets:cash    = $0-  expenses:misc-.EE-.PP-The calculated amount depends on the account\[aq]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).-.PP-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\[aq] forcing of balances can hide errors.-These things make your financial data less portable, less future\-proof,-and less trustworthy in an audit.-.SS Balance assignments and costs-A cost in a balance assignment will cause the calculated amount to have-that cost attached:-.IP-.EX-2019/1/1-  (a)             = $1 \[at] €2-.EE-.IP-.EX-$ hledger print \-\-explicit-2019\-01\-01-    (a)         $1 \[at] €2 = $1 \[at] €2-.EE-.SS 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.-.SS Bracketed posting dates-For setting posting dates and secondary posting dates, Ledger\[aq]s-bracketed date syntax is also supported: \f[CR][DATE]\f[R],-\f[CR][DATE=DATE2]\f[R] or \f[CR][=DATE2]\f[R] in posting comments.-hledger will attempt to parse any square\-bracketed sequence of the-\f[CR]0123456789/\-.=\f[R] characters in this way.-With this syntax, DATE infers its year from the transaction and DATE2-infers its year from DATE.-.PP-Downsides: another syntax to learn, redundant with hledger\[aq]s-\f[CR]date:\f[R]/\f[CR]date2:\f[R] tags, and confusingly similar to-Ledger\[aq]s lot date syntax.-.SS \f[CR]D\f[R] directive-\f[CR]D AMOUNT\f[R]-.PP-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 \f[CR]D\f[R] directive, or the end of-the current file.-.PP-For compatibility/historical reasons, \f[CR]D\f[R] also acts like a-\f[CR]commodity\f[R] directive (setting the commodity\[aq]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:-.IP-.EX-; 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-.EE-.PP-Interactions with other directives:-.PP-For setting a commodity\[aq]s display style, a \f[CR]commodity\f[R]-directive has highest priority, then a \f[CR]D\f[R] directive.-.PP-For detecting a commodity\[aq]s decimal mark during parsing,-\f[CR]decimal\-mark\f[R] has highest priority, then-\f[CR]commodity\f[R], then \f[CR]D\f[R].-.PP-For checking commodity symbols with the check command, a-\f[CR]commodity\f[R] directive is required-(\f[CR]hledger check commodities\f[R] ignores \f[CR]D\f[R] directives).-.PP-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 \f[CR]commodity\f[R] and-\f[CR]decimal\-mark\f[R].-And it works differently from Ledger\[aq]s \f[CR]D\f[R].-.SS \f[CR]apply account\f[R] directive-This directive sets a default parent account, which will be prepended to-all accounts in following entries, until an \f[CR]end apply account\f[R]-directive or end of current file.-Eg:-.IP-.EX-apply account home--2010/1/1-    food    $10-    cash--end apply account-.EE-.PP-is equivalent to:-.IP-.EX-2010/01/01-    home:food           $10-    home:cash          $\-10-.EE-.PP-\f[CR]account\f[R] directives are also affected, and so is any-\f[CR]include\f[R]d content.-.PP-Account names entered via hledger add or hledger\-web are not affected.-.PP-Account aliases, if any, are applied after the parent account is-prepended.-.PP-Downsides: this can make your financial data less explicit, less-portable, and less trustworthy in an audit.-.SS \f[CR]Y\f[R] directive-\f[CR]Y YEAR\f[R]-.PP-or (deprecated backward\-compatible forms):-.PP-\f[CR]year YEAR\f[R] \f[CR]apply year YEAR\f[R]-.PP-The space is optional.-This sets a default year to be used for subsequent dates which don\[aq]t-specify a year.-Eg:-.IP-.EX-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-.EE-.PP-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\[aq]s date.-.SS Secondary dates-A secondary date is written after the primary date, following an equals-sign.-If the year is omitted, the primary date\[aq]s year is assumed.-When running reports, the primary (left) date is used by default, but-with the \f[CR]\-\-date2\f[R] flag (or \f[CR]\-\-aux\-date\f[R] or-\f[CR]\-\-effective\f[R]), the secondary (right) date will be used-instead.-.PP-The meaning of secondary dates is up to you, but it\[aq]s best to follow-a consistent rule.-Eg \[dq]primary = the bank\[aq]s clearing date, secondary = date the-transaction was initiated, if different\[dq].-.PP-Downsides: makes your financial data more complicated, less portable,-and less trustworthy in an audit.-Keeping the meaning of the two dates consistent requires discipline, and-you have to remember which reporting mode is appropriate for a given-report.-Posting dates are simpler and better.-.SS Star comments-Lines beginning with \f[CR]*\f[R] (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.-.PP-Downsides: another, unconventional comment syntax to learn.-Decreases your journal\[aq]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\[aq]s features.-.SS Valuation expressions-Ledger allows a valuation function or value to be written in double-parentheses after an amount.-hledger ignores these.-.SS Virtual postings-A posting with parentheses around the account name, like-\f[CR](some:account)   10\f[R], is called an \f[I]unbalanced virtual-posting\f[R].-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.-.PP-A posting with brackets around the account name-(\f[CR][some:account]\f[R]) is called a \f[I]balanced virtual-posting\f[R].-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:-.IP-.EX-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-.EE-.PP-Ordinary postings, whose account names are neither parenthesised nor-bracketed, are called \f[I]real postings\f[R].-You can exclude virtual postings from reports with the-\f[CR]\-R/\-\-real\f[R] flag or a \f[CR]real:1\f[R] query.-.SS 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\[aq]s reports may differ from Ledger\[aq]s if you use these.-.IP-.EX-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-.EE-.PP-See also https://hledger.org/ledger.html for a detailed hledger/Ledger-syntax comparison.-.SS Other cost/lot notations-A slight digression for Ledger and Beancount users.-Ledger has a number of cost/lot\-related notations:-.IP \[bu] 2-\f[CR]\[at] UNITCOST\f[R] and \f[CR]\[at]\[at] TOTALCOST\f[R]-.RS 2-.IP \[bu] 2-expresses a conversion rate, as in hledger-.IP \[bu] 2-when buying, also creates a lot than can be selected at selling time-.RE-.IP \[bu] 2-\f[CR](\[at]) UNITCOST\f[R] and \f[CR](\[at]\[at]) TOTALCOST\f[R]-(virtual cost)-.RS 2-.IP \[bu] 2-like the above, but also means \[dq]this cost was exceptional, don\[aq]t-use it when inferring market prices\[dq].-.RE-.PP-Currently, hledger treats the above like \f[CR]\[at]\f[R] and-\f[CR]\[at]\[at]\f[R]; the parentheses are ignored.-.IP \[bu] 2-\f[CR]{=FIXEDUNITCOST}\f[R] and \f[CR]{{=FIXEDTOTALCOST}}\f[R] (fixed-price)-.RS 2-.IP \[bu] 2-when buying, means \[dq]this cost is also the fixed price, don\[aq]t let-it fluctuate in value reports\[dq]-.RE-.IP \[bu] 2-\f[CR]{UNITCOST}\f[R] and \f[CR]{{TOTALCOST}}\f[R] (lot price)-.RS 2-.IP \[bu] 2-can be used identically to \f[CR]\[at] UNITCOST\f[R] and-\f[CR]\[at]\[at] TOTALCOST\f[R], also creates a lot-.IP \[bu] 2-when selling, combined with \f[CR]\[at] ...\f[R], specifies an-investment lot by its cost basis; does not check if that lot is present-.RE-.IP \[bu] 2-and related: \f[CR][YYYY/MM/DD]\f[R] (lot date)-.RS 2-.IP \[bu] 2-when buying, attaches this acquisition date to the lot-.IP \[bu] 2-when selling, selects a lot by its acquisition date-.RE-.IP \[bu] 2-\f[CR](SOME TEXT)\f[R] (lot note)-.RS 2-.IP \[bu] 2-when buying, attaches this note to the lot-.IP \[bu] 2-when selling, selects a lot by its note-.RE-.PP-Currently, hledger accepts any or all of the above in any order after-the posting amount, but ignores them.-(This can break transaction balancing.)-.PP-For Beancount users, the notation and behaviour is different:-.IP \[bu] 2-\f[CR]\[at] UNITCOST\f[R] and \f[CR]\[at]\[at] TOTALCOST\f[R]-.RS 2-.IP \[bu] 2-expresses a cost without creating a lot, as in hledger-.IP \[bu] 2-when buying (augmenting) or selling (reducing) a lot, combined with-\f[CR]{...}\f[R]: documents the cost/selling price (not used for-transaction balancing)-.RE-.IP \[bu] 2-\f[CR]{UNITCOST}\f[R] and \f[CR]{{TOTALCOST}}\f[R]-.RS 2-.IP \[bu] 2-when buying (augmenting), expresses the cost for transaction balancing,-and also creates a lot with this cost basis attached-.IP \[bu] 2-when selling (reducing),-.RS 2-.IP \[bu] 2-selects a lot by its cost basis-.IP \[bu] 2-raises an error if that lot is not present or can not be selected-unambiguously (depending on booking method configured)-.IP \[bu] 2-expresses the selling price for transaction balancing-.RE-.RE-.PP-Currently, hledger accepts the-\f[CR]{UNITCOST}\f[R]/\f[CR]{{TOTALCOST}}\f[R] notation but ignores it.-.IP \[bu] 2-variations: \f[CR]{}\f[R], \f[CR]{YYYY\-MM\-DD}\f[R],-\f[CR]{\[dq]LABEL\[dq]}\f[R], \f[CR]{UNITCOST, \[dq]LABEL\[dq]}\f[R],-\f[CR]{UNITCOST, YYYY\-MM\-DD, \[dq]LABEL\[dq]}\f[R] etc.-.PP-Currently, hledger rejects these.-.PP-.SH CSV-hledger can read CSV files (Character Separated Value \- usually comma,-semicolon, or tab) containing dated records, automatically converting-each record into a transaction.-.PP-(To learn about \f[I]writing\f[R] CSV, see CSV output.)-.PP-For best error messages when reading CSV/TSV/SSV files, make sure they-have a corresponding \f[CR].csv\f[R], \f[CR].tsv\f[R] or \f[CR].ssv\f[R]-file extension or use a hledger file prefix (see File Extension below).-.PP-Each CSV file must be described by a corresponding \f[I]rules file\f[R].-.PD 0-.P-.PD-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.-.PP-By default, hledger expects this rules file to be named like the CSV-file, with an extra \f[CR].rules\f[R] extension added, in the same-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.-.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-are.-Here\[aq]s a simple CSV file and a rules file for it:-.IP-.EX-Date, Description, Id, Amount-12/11/2019, Foo, 123, 10.23-.EE-.IP-.EX-# basic.csv.rules-skip         1-fields       date, description, , amount-date\-format  %d/%m/%Y-.EE-.IP-.EX-$ hledger print \-f basic.csv-2019\-11\-12 Foo-    expenses:unknown           10.23-    income:unknown            \-10.23-.EE-.PP-There\[aq]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.-.SS CSV rules cheatsheet-The following kinds of rule can appear in the rules file, in any order.-(Blank lines and lines beginning with \f[CR]#\f[R] or \f[CR];\f[R] or-\f[CR]*\f[R] are ignored.)-.PP-.TS-tab(@);-lw(23.7n) lw(46.3n).-T{-\f[B]\f[CB]source\f[B]\f[R]-T}@T{-optionally declare which file to read data from-T}-T{-\f[B]\f[CB]separator\f[B]\f[R]-T}@T{-declare the field separator, instead of relying on file extension-T}-T{-\f[B]\f[CB]skip\f[B]\f[R]-T}@T{-skip one or more header lines at start of file-T}-T{-\f[B]\f[CB]date\-format\f[B]\f[R]-T}@T{-declare how to parse CSV dates/date\-times-T}-T{-\f[B]\f[CB]timezone\f[B]\f[R]-T}@T{-declare the time zone of ambiguous CSV date\-times-T}-T{-\f[B]\f[CB]newest\-first\f[B]\f[R]-T}@T{-improve txn order when: there are multiple records, newest first, all-with the same date-T}-T{-\f[B]\f[CB]intra\-day\-reversed\f[B]\f[R]-T}@T{-improve txn order when: same\-day txns are in opposite order to the-overall file-T}-T{-\f[B]\f[CB]decimal\-mark\f[B]\f[R]-T}@T{-declare the decimal mark used in CSV amounts, when ambiguous-T}-T{-\f[B]\f[CB]fields\f[B] list\f[R]-T}@T{-name CSV fields for easy reference, and optionally assign their values-to hledger fields-T}-T{-\f[B]Field assignment\f[R]-T}@T{-assign a CSV value or interpolated text value to a hledger field-T}-T{-\f[B]\f[CB]if\f[B] block\f[R]-T}@T{-conditionally assign values to hledger fields, or \f[CR]skip\f[R] a-record or \f[CR]end\f[R] (skip rest of file)-T}-T{-\f[B]\f[CB]if\f[B] table\f[R]-T}@T{-conditionally assign values to hledger fields, using compact syntax-T}-T{-\f[B]\f[CB]balance\-type\f[B]\f[R]-T}@T{-select which type of balance assertions/assignments to generate-T}-T{-\f[B]\f[CB]include\f[B]\f[R]-T}@T{-inline another CSV rules file-T}-.TE-.PP-Working with CSV tips can be found below, including How CSV rules are-evaluated.-.SS \f[CR]source\f[R]-If you tell hledger to read a csv file with \f[CR]\-f foo.csv\f[R], it-will look for rules in \f[CR]foo.csv.rules\f[R].-Or, you can tell it to read the rules file, with-\f[CR]\-f foo.csv.rules\f[R], and it will look for data in-\f[CR]foo.csv\f[R] (since 1.30).-.PP-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 \[dq]source\[dq]-rule:-.IP-.EX-source ./Checking1.csv-.EE-.PP-If you specify just a file name with no path, hledger will look for it-in your system\[aq]s downloads directory (\f[CR]\[ti]/Downloads\f[R],-currently):-.IP-.EX-source Checking1.csv-.EE-.PP-And if you specify a glob pattern, hledger will read the most recent of-the matched files (useful with repeated downloads):-.IP-.EX-source Checking1*.csv-.EE-.PP-See also \[dq]Working with CSV > Reading files specified by rule\[dq].-.SS \f[CR]separator\f[R]-You can use the \f[CR]separator\f[R] rule to read other kinds of-character\-separated data.-The argument is any single separator character, or the words-\f[CR]tab\f[R] or \f[CR]space\f[R] (case insensitive).-Eg, for comma\-separated values (CSV):-.IP-.EX-separator ,-.EE-.PP-or for semicolon\-separated values (SSV):-.IP-.EX-separator ;-.EE-.PP-or for tab\-separated values (TSV):-.IP-.EX-separator TAB-.EE-.PP-If the input file has a \f[CR].csv\f[R], \f[CR].ssv\f[R] or-\f[CR].tsv\f[R] file extension (or a \f[CR]csv:\f[R], \f[CR]ssv:\f[R],-\f[CR]tsv:\f[R] prefix), the appropriate separator will be inferred-automatically, and you won\[aq]t need this rule.-.SS \f[CR]skip\f[R]-.IP-.EX-skip N-.EE-.PP-The word \f[CR]skip\f[R] 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\[aq]ll need this whenever your CSV data contains header lines.-Note, empty and blank lines are skipped automatically, so you don\[aq]t-need to count those.-.PP-\f[CR]skip\f[R] 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.-.SS \f[CR]date\-format\f[R]-.IP-.EX-date\-format DATEFMT-.EE-.PP-This is a helper for the \f[CR]date\f[R] (and \f[CR]date2\f[R]) fields.-If your CSV dates are not formatted like \f[CR]YYYY\-MM\-DD\f[R],-\f[CR]YYYY/MM/DD\f[R] or \f[CR]YYYY.MM.DD\f[R], you\[aq]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:-.IP-.EX-# MM/DD/YY-date\-format %m/%d/%y-.EE-.IP-.EX-# D/M/YYYY-# The \- makes leading zeros optional.-date\-format %\-d/%\-m/%Y-.EE-.IP-.EX-# YYYY\-Mmm\-DD-date\-format %Y\-%h\-%d-.EE-.IP-.EX-# 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-.EE-.SS \f[CR]timezone\f[R]-.IP-.EX-timezone TIMEZONE-.EE-.PP-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\[aq]s native time zone, which helps-prevent off\-by\-one dates.-.PP-When the CSV date\-times do contain time zone information, you don\[aq]t-need this rule; instead, use \f[CR]%Z\f[R] in \f[CR]date\-format\f[R]-(or \f[CR]%z\f[R], \f[CR]%EZ\f[R], \f[CR]%Ez\f[R]; see the formatTime-link above).-.PP-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:-.IP-.EX-$ TZ=\-1000 hledger print \-f foo.csv  # or TZ=\-1000 hledger import foo.csv-.EE-.PP-\f[CR]timezone\f[R] currently does not understand timezone names, except-\[dq]UTC\[dq], \[dq]GMT\[dq], \[dq]EST\[dq], \[dq]EDT\[dq],-\[dq]CST\[dq], \[dq]CDT\[dq], \[dq]MST\[dq], \[dq]MDT\[dq],-\[dq]PST\[dq], or \[dq]PDT\[dq].-For others, use numeric format: +HHMM or \-HHMM.-.SS \f[CR]newest\-first\f[R]-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\[aq]s records are normally newest first, like:-.IP-.EX-2022\-10\-01, txn 3...-2022\-10\-01, txn 2...-2022\-10\-01, txn 1...-.EE-.PP-you can add the \f[CR]newest\-first\f[R] rule to help hledger generate-the transactions in correct order.-.IP-.EX-# same\-day CSV records are newest first-newest\-first-.EE-.SS \f[CR]intra\-day\-reversed\f[R]-If CSV records within a single day are ordered opposite to the overall-record order, you can add the \f[CR]intra\-day\-reversed\f[R] rule to-improve the order of journal entries.-Eg, here the overall record order is newest first, but same\-day records-are oldest first:-.IP-.EX-2022\-10\-02, txn 3...-2022\-10\-02, txn 4...-2022\-10\-01, txn 1...-2022\-10\-01, txn 2...-.EE-.IP-.EX-# transactions within each day are reversed with respect to the overall date order-intra\-day\-reversed-.EE-.SS \f[CR]decimal\-mark\f[R]-.IP-.EX-decimal\-mark .-.EE-.PP-or:-.IP-.EX-decimal\-mark ,-.EE-.PP-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.-.SS \f[CR]fields\f[R] list-.IP-.EX-fields FIELDNAME1, FIELDNAME2, ...-.EE-.PP-A fields list (the word \f[CR]fields\f[R] followed by comma\-separated-field names) is optional, but convenient.-It does two things:-.IP "1." 3-It names the CSV field in each column.-This can be convenient if you are referencing them in other rules, so-you can say \f[CR]%SomeField\f[R] instead of remembering \f[CR]%13\f[R].-.IP "2." 3-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\[aq]s fields and build a-transaction.-.PP-Here\[aq]s an example that says \[dq]use the 1st, 2nd and 4th fields as-the transaction\[aq]s date, description and amount; name the last two-fields for later reference; and ignore the others\[dq]:-.IP-.EX-fields date, description, , amount, , , somefield, anotherfield-.EE-.PP-In a fields list, the separator is always comma; it is unrelated to the-CSV file\[aq]s separator.-Also:-.IP \[bu] 2-There must be least two items in the list (at least one comma).-.IP \[bu] 2-Field names may not contain spaces.-Spaces before/after field names are optional.-.IP \[bu] 2-Field names may contain \f[CR]_\f[R] (underscore) or \f[CR]\-\f[R]-(hyphen).-.IP \[bu] 2-Fields you don\[aq]t care about can be given a dummy name or an empty-name.-.PP-If the CSV contains column headings, it\[aq]s convenient to use these-for your field names, suitably modified (eg lower\-cased with spaces-replaced by underscores).-.PP-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\[aq]s \[dq]balance\[dq] field-\f[CR]balance_\f[R] to avoid directly setting hledger\[aq]s-\f[CR]balance\f[R] field (and generating a balance assertion).-.SS Field assignment-.IP-.EX-HLEDGERFIELD FIELDVALUE-.EE-.PP-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).-.PP-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 (\f[CR]%N\f[R]) or by the name they-were given in the fields list (\f[CR]%CSVFIELD\f[R]), and regular-expression match groups (\f[CR]\[rs]N\f[R]).-.PP-Some examples:-.IP-.EX-# set the amount to the 4th CSV field, with \[dq] USD\[dq] appended-amount %4 USD--# combine three fields to make a comment, containing note: and date: tags-comment note: %somefield \- %anotherfield, date: %1-.EE-.PP-Tips:-.IP \[bu] 2-Interpolation strips outer whitespace (so a CSV value like-\f[CR]\[dq] 1 \[dq]\f[R] becomes \f[CR]1\f[R] when interpolated)-(#1051).-.IP \[bu] 2-Interpolations always refer to a CSV field \- you can\[aq]t interpolate-a hledger field.-(See Referencing other fields below).-.SS Field names-Note the two kinds of field names mentioned here, and used only in-hledger CSV rules files:-.IP "1." 3-\f[B]CSV field names\f[R] (\f[CR]CSVFIELD\f[R] in these docs): you can-optionally name the CSV columns for easy reference (since hledger-doesn\[aq]t yet automatically recognise column headings in a CSV file),-by writing arbitrary names in a \f[CR]fields\f[R] list, eg:-.RS 4-.IP-.EX-fields When, What, Some_Id, Net, Total, Foo, Bar-.EE-.RE-.IP "2." 3-Special \f[B]hledger field names\f[R] (\f[CR]HLEDGERFIELD\f[R] 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:-.RS 4-.IP-.EX-date        %When-code        %Some_Id-description %What-comment     %Foo %Bar-amount1     $ %Total-.EE-.PP-or directly in a \f[CR]fields\f[R] list:-.IP-.EX-fields date, description, code, , amount1, Foo, Bar-currency $-comment  %Foo %Bar-.EE-.RE-.PP-Here are all the special hledger field names available, and what happens-when you assign values to them:-.SS date field-Assigning to \f[CR]date\f[R] sets the transaction date.-.SS date2 field-\f[CR]date2\f[R] sets the transaction\[aq]s secondary date, if any.-.SS status field-\f[CR]status\f[R] sets the transaction\[aq]s status, if any.-.SS code field-\f[CR]code\f[R] sets the transaction\[aq]s code, if any.-.SS description field-\f[CR]description\f[R] sets the transaction\[aq]s description, if any.-.SS comment field-\f[CR]comment\f[R] sets the transaction\[aq]s comment, if any.-.PP-\f[CR]commentN\f[R], where N is a number, sets the Nth posting\[aq]s-comment.-.PP-You can assign multi\-line comments by writing literal \f[CR]\[rs]n\f[R]-in the code.-A comment starting with \f[CR]\[rs]n\f[R] will begin on a new line.-.PP-Comments can contain tags, as usual.-.SS account field-Assigning to \f[CR]accountN\f[R], where N is 1 to 99, sets the account-name of the Nth posting, and causes that posting to be generated.-.PP-Most often there are two postings, so you\[aq]ll want to set-\f[CR]account1\f[R] and \f[CR]account2\f[R].-Typically \f[CR]account1\f[R] is associated with the CSV file, and is-set once with a top\-level assignment, while \f[CR]account2\f[R] is set-based on each transaction\[aq]s description, in conditional rules.-.PP-If a posting\[aq]s account name is left unset but its amount is set (see-below), a default account name will be chosen (like-\[dq]expenses:unknown\[dq] or \[dq]income:unknown\[dq]).-.SS amount field-There are several ways to set posting amounts from CSV, useful in-different situations.-.IP "1." 3-\f[B]\f[CB]amount\f[B]\f[R] 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.-.IP "2." 3-\f[B]\f[CB]amount\-in\f[B]\f[R] and \f[B]\f[CB]amount\-out\f[B]\f[R]-work exactly like the above, but should be used when the CSV has two-amount fields (such as \[dq]Debit\[dq] and \[dq]Credit\[dq], or-\[dq]Inflow\[dq] and \[dq]Outflow\[dq]).-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:-.RS 4-.IP \[bu] 2-It\[aq]s not \[dq]amount\-in for posting 1 and amount\-out for posting-2\[dq], it is \[dq]extract a single amount from the amount\-in or-amount\-out field, and use that for posting 1 and (negated) for posting-2\[dq].-.IP \[bu] 2-Don\[aq]t use both \f[CR]amount\f[R] and-\f[CR]amount\-in\f[R]/\f[CR]amount\-out\f[R] in the same rules file;-choose based on whether the amount is in a single CSV field or spread-across two fields.-.IP \[bu] 2-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.-.IP \[bu] 2-hledger assumes both CSV fields contain unsigned numbers, and it-automatically negates the amount\-out values.-.IP \[bu] 2-If the data doesn\[aq]t fit these requirements, you\[aq]ll probably need-an if rule (see below).-.RE-.IP "3." 3-\f[B]\f[CB]amountN\f[B]\f[R] (where N is a number from 1 to 99) sets the-amount of only a single posting: the Nth posting in the transaction.-You\[aq]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\[aq]t have to be consecutive; with if rules,-higher posting numbers can be useful to ensure a certain order of-postings.-.IP "4." 3-\f[B]\f[CB]amountN\-in\f[B]\f[R] and \f[B]\f[CB]amountN\-out\f[B]\f[R]-work exactly like the above, but should be used when the CSV has two-amount fields.-This is analogous to \f[CR]amount\-in\f[R] and \f[CR]amount\-out\f[R],-and those tips also apply here.-.IP "5." 3-Remember that a \f[CR]fields\f[R] list can also do assignments.-So in a fields list if you name a CSV field \[dq]amount\[dq], that-counts as assigning to \f[CR]amount\f[R].-(If you don\[aq]t want that, call it something else in the fields list,-like \[dq]amount_\[dq].)-.IP "6." 3-The above don\[aq]t handle every situation; if you need more-flexibility, use an \f[CR]if\f[R] rule to set amounts conditionally.-See \[dq]Working with CSV > Setting amounts\[dq] below for more on this-and on amount\-setting generally.-.SS currency field-\f[CR]currency\f[R] sets a currency symbol, to be prepended to all-postings\[aq] amounts.-You can use this if the CSV amounts do not have a currency symbol, eg if-it is in a separate column.-.PP-\f[CR]currencyN\f[R] prepends a currency symbol to just the Nth-posting\[aq]s amount.-.SS balance field-\f[CR]balanceN\f[R] sets a balance assertion amount (or if the posting-amount is left empty, a balance assignment) on posting N.-.PP-\f[CR]balance\f[R] is a compatibility spelling for hledger <1.17; it is-equivalent to \f[CR]balance1\f[R].-.PP-You can adjust the type of assertion/assignment with the-\f[CR]balance\-type\f[R] rule (see below).-.PP-See the Working with CSV tips below for more about setting amounts and-currency.-.SS \f[CR]if\f[R] 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: \[dq]if blocks\[dq],-described here, and \[dq]if tables\[dq], described below.-.PP-An if block is the word \f[CR]if\f[R] and one or more \[dq]matcher\[dq]-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,-.IP-.EX-if MATCHER- RULE-.EE-.PP-or-.IP-.EX-if-MATCHER-MATCHER-MATCHER- RULE- RULE-.EE-.PP-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:-.IP \[bu] 2-\f[CR]skip\f[R] \- skips the matched CSV record (generating no-transaction from it)-.IP \[bu] 2-\f[CR]end\f[R] \- skips the rest of the current CSV file.-.PP-Some examples:-.IP-.EX-# if the record contains \[dq]groceries\[dq], set account2 to \[dq]expenses:groceries\[dq]-if groceries- account2 expenses:groceries-.EE-.IP-.EX-# 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-.EE-.IP-.EX-# if an empty record is seen (assuming five fields), ignore the rest of the CSV file-if ,,,,- end-.EE-.SS Matchers-There are two kinds:-.IP "1." 3-A record matcher is a word or single\-line text fragment or regular-expression (\f[CR]REGEX\f[R]), which hledger will try to match-case\-insensitively anywhere within the CSV record.-.PD 0-.P-.PD-Eg: \f[CR]whole foods\f[R]-.IP "2." 3-A field matcher is preceded with a percent sign and CSV field name-(\f[CR]%CSVFIELD REGEX\f[R]).-hledger will try to match these just within the named CSV field.-.PD 0-.P-.PD-Eg: \f[CR]%date 2023\f[R]-.PP-The regular expression is (as usual in hledger) a POSIX extended regular-expression, that also supports GNU word boundaries (\f[CR]\[rs]b\f[R],-\f[CR]\[rs]B\f[R], \f[CR]\[rs]<\f[R], \f[CR]\[rs]>\f[R]), and nothing-else.-If you have trouble, see \[dq]Regular expressions\[dq] in the hledger-manual (https://hledger.org/hledger.html#regular\-expressions).-.SS What matchers match-With record matchers, it\[aq]s important to know that the record matched-is not the original CSV record, but a modified one: separators will be-converted to commas, and enclosing double quotes (but not enclosing-whitespace) are removed.-So for example, when reading an SSV file, if the original record was:-.IP-.EX-2023\-01\-01; \[dq]Acme, Inc.\[dq];  1,000-.EE-.PP-the regex would see, and try to match, this modified record text:-.IP-.EX-2023\-01\-01,Acme, Inc.,  1,000-.EE-.SS Combining matchers-When an if block has multiple matchers, they are combined as follows:-.IP \[bu] 2-By default they are OR\[aq]d (any of them can match)-.IP \[bu] 2-When a matcher is preceded by ampersand (\f[CR]&\f[R], at the start of-the line) it will be AND\[aq]ed with the previous matcher (all in the-AND\[aq]ed group must match)-.IP \[bu] 2-\f[I]Added in 1.32\f[R] When a matcher is preceded by an exclamation-mark (\f[CR]!\f[R]), it is negated (it must not match).-.PP-Note currently there is a limitation: you can\[aq]t use both-\f[CR]&\f[R] and \f[CR]!\f[R] on the same line (you can\[aq]t AND a-negated matcher).-.SS Match groups-\f[I]Added in 1.32\f[R]-.PP-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 (\f[CR](\f[R] and-\f[CR])\f[R]) and can be nested.-Each group is available in field assignments using the token-\f[CR]\[rs]N\f[R], where N is an index into the match groups for this-conditional block (e.g.-\f[CR]\[rs]1\f[R], \f[CR]\[rs]2\f[R], etc.).-.PP-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:-.IP-.EX-if %date (....\-..)\-..-  comment2 date:\[rs]1\-01-.EE-.PP-Another example: Read the expense account from the CSV field, but throw-away a prefix:-.IP-.EX-if %account1 liabilities:family:(expenses:.*)-    account1 \[rs]1-.EE-.SS \f[CR]if\f[R] table-\[dq]if tables\[dq] are an alternative to if blocks; they can express-many matchers and field assignments in a more compact tabular format,-like this:-.IP-.EX-if,HLEDGERFIELD1,HLEDGERFIELD2,...-MATCHERA,VALUE1,VALUE2,...-MATCHERB,VALUE1,VALUE2,...-; Comment line that explains MATCHERC-MATCHERC,VALUE1,VALUE2,...-<empty line>-.EE-.PP-The first character after \f[CR]if\f[R] is taken to be this if-table\[aq]s field separator.-It is unrelated to the separator used in the CSV file.-It should be a non\-alphanumeric character like \f[CR],\f[R] or-\f[CR]|\f[R] 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).-.PP-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).-.PP-An if table like the above is interpreted as follows: try all of the-matchers; whenever a matcher succeeds, assign all of the values on that-line to the corresponding hledger fields; If multiple lines match, later-lines will override fields assigned by the earlier ones \- just like the-sequence of \f[CR]if\f[R] blocks would behave.-.PP-If table presented above is equivalent to this sequence of if blocks:-.IP-.EX-if MATCHERA-  HLEDGERFIELD1 VALUE1-  HLEDGERFIELD2 VALUE2-  ...--if MATCHERB-  HLEDGERFIELD1 VALUE1-  HLEDGERFIELD2 VALUE2-  ...--; Comment line which explains MATCHERC-if MATCHERC-  HLEDGERFIELD1 VALUE1-  HLEDGERFIELD2 VALUE2-  ...-.EE-.PP-Example:-.IP-.EX-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-.EE-.SS \f[CR]balance\-type\f[R]-Balance assertions generated by assigning to balanceN are of the simple-\f[CR]=\f[R] 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-\f[CR]balance\-type\f[R] rule:-.IP-.EX-# balance assertions will consider all commodities and all subaccounts-balance\-type ==*-.EE-.PP-Here are the balance assertion types for quick reference:-.IP-.EX-=    single commodity, exclude subaccounts-=*   single commodity, include subaccounts-==   multi commodity,  exclude subaccounts-==*  multi commodity,  include subaccounts-.EE-.SS \f[CR]include\f[R]-.IP-.EX-include RULESFILE-.EE-.PP-This includes the contents of another CSV rules file at this point.-\f[CR]RULESFILE\f[R] is an absolute file path or a path relative to the-current file\[aq]s directory.-This can be useful for sharing common rules between several rules files,-eg:-.IP-.EX-# someaccount.csv.rules--## someaccount\-specific rules-fields   date,description,amount-account1 assets:someaccount-account2 expenses:misc--## common rules-include categorisation.rules-.EE-.SS Working with CSV-Some tips:-.SS Rapid feedback-It\[aq]s a good idea to get rapid feedback while-creating/troubleshooting CSV rules.-Here\[aq]s a good way, using entr from eradman.com/entrproject:-.IP-.EX-$ ls foo.csv* | entr bash \-c \[aq]echo \-\-\-\-; hledger \-f foo.csv print desc:SOMEDESC\[aq]-.EE-.PP-A desc: query (eg) is used to select just one, or a few, transactions of-interest.-\[dq]bash \-c\[dq] 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.-.SS 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:-.IP \[bu] 2-Values may be enclosed in double quotes, or not.-Enclosing in single quotes is not allowed.-(Eg \f[CR]\[aq]A\[aq],\[aq]B\[aq]\f[R] is rejected.)-.IP \[bu] 2-When values are enclosed in double quotes, spaces outside the quotes are-not allowed.-(Eg \f[CR]\[dq]A\[dq], \[dq]B\[dq]\f[R] is rejected.)-.IP \[bu] 2-When values are not enclosed in quotes, they may not contain double-quotes.-(Eg \f[CR]A\[dq]A, B\f[R] is rejected.)-.PP-If your CSV/SSV/TSV is not valid in this sense, you\[aq]ll need to-transform it before reading with hledger.-Try using sed, or a more permissive CSV parser like python\[aq]s csv-lib.-.SS 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\[aq]s best if CSV/SSV/TSV files are named with a \f[CR].csv\f[R],-\f[CR].ssv\f[R] or \f[CR].tsv\f[R] filename extension.-(More about this at Data formats.)-.PP-When reading files with the \[dq]wrong\[dq] extension, you can ensure-the CSV reader (and the default field separator) by prefixing the file-path with \f[CR]csv:\f[R], \f[CR]ssv:\f[R] or \f[CR]tsv:\f[R]: Eg:-.IP-.EX-$ hledger \-f ssv:foo.dat print-.EE-.PP-You can also override the default field separator with a separator rule-if needed.-.SS Reading CSV from standard input-You\[aq]ll need the file format prefix when reading CSV from stdin also,-since hledger assumes journal format by default.-Eg:-.IP-.EX-$ cat foo.dat | hledger \-f ssv:\- print-.EE-.SS Reading multiple CSV files-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.-.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].-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\[aq]s download directory.-.PP-This feature was added in hledger 1.30, so you won\[aq]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\[aq]s default CSV filenames are-different and can be recognised by a glob pattern.-So you can put a rule like \f[CR]source Checking1*.csv\f[R] in-foo\-checking.csv.rules, and then periodically follow a workflow like:-.IP "1." 3-Download CSV from Foo\[aq]s website, using your browser\[aq]s defaults-.IP "2." 3-Run \f[CR]hledger import foo\-checking.csv.rules\f[R] to import any new-transactions-.PP-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 \f[CR]*\f[R]-wild card and because it is the most recent.-.SS 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.-.PP-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:-.IP-.EX-$ hledger \-f file.csv print | hledger \-f\- print-.EE-.SS 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.-.PP-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\[aq]t have to remember how many times you-ran it or with which version of the CSV.-(It keeps state in a hidden \f[CR].latest.FILE.csv\f[R] file.)-This is the easiest way to import CSV data.-Eg:-.IP-.EX-# download the latest CSV files, then run this command.-# Note, no \-f flags needed here.-$ hledger import *.csv [\-\-dry]-.EE-.PP-This method works for most CSV files.-(Where records have a stable chronological order, and new records appear-only at the new end.)-.PP-A number of other tools and workflows, hledger\-specific and otherwise,-exist for converting, deduplicating, classifying and managing CSV data.-See:-.IP \[bu] 2-https://hledger.org/cookbook.html#setups\-and\-workflows-.IP \[bu] 2-https://plaintextaccounting.org \-> data import/conversion-.SS Setting amounts-Continuing from amount field above, here are more tips for-amount\-setting:-.IP "1." 3-\f[B]If the amount is in a single CSV field:\f[R]-.PD 0-.P-.PD-.RS 4-.IP "a." 3-\f[B]If its sign indicates direction of flow:\f[R]-.PD 0-.P-.PD-Assign it to \f[CR]amountN\f[R], to set the Nth posting\[aq]s amount.-N is usually 1 or 2 but can go up to 99.-.IP "b." 3-\f[B]If another field indicates direction of flow:\f[R]-.PD 0-.P-.PD-Use one or more conditional rules to set the appropriate amount sign.-Eg:-.IP-.EX-# assume a withdrawal unless Type contains \[dq]deposit\[dq]:-amount1  \-%Amount-if %Type deposit-  amount1  %Amount-.EE-.RE-.IP "2." 3-\f[B]If the amount is in two CSV fields (such as Debit and Credit, or In-and Out):\f[R]-.PD 0-.P-.PD-.RS 4-.IP "a." 3-\f[B]If both fields are unsigned:\f[R]-.PD 0-.P-.PD-Assign one field to \f[CR]amountN\-in\f[R] and the other to-\f[CR]amountN\-out\f[R].-hledger will automatically negate the \[dq]out\[dq] field, and will use-whichever field value is non\-zero as posting N\[aq]s amount.-.IP "b." 3-\f[B]If either field is signed:\f[R]-.PD 0-.P-.PD-You will probably need to override hledger\[aq]s sign for one or the-other field, as in the following example:-.IP-.EX-# 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-.EE-.IP "c." 3-\f[B]If both fields can contain a non\-zero value (or both can be-empty):\f[R]-.PD 0-.P-.PD-The \-in/\-out rules normally choose the value which is-non\-zero/non\-empty.-Some value pairs can be ambiguous, such as \f[CR]1\f[R] and-\f[CR]none\f[R].-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:-.IP-.EX-fields date, description, in, out-if %in [1\-9]- amount1 %in-if %out [1\-9]- amount1 %out-.EE-.RE-.IP "3." 3-\f[B]If you want posting 2\[aq]s amount converted to cost:\f[R]-.PD 0-.P-.PD-Use the unnumbered \f[CR]amount\f[R] (or \f[CR]amount\-in\f[R] and-\f[CR]amount\-out\f[R]) syntax.-.IP "4." 3-\f[B]If the CSV has only balance amounts, not transaction amounts:\f[R]-.PD 0-.P-.PD-Assign to \f[CR]balanceN\f[R], to set a balance assignment on the Nth-posting, causing the posting\[aq]s amount to be calculated-automatically.-\f[CR]balance\f[R] with no number is equivalent to \f[CR]balance1\f[R].-In this situation hledger is more likely to guess the wrong default-account name, so you may need to set that explicitly.-.SS 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-\f[CR]amount1  AMT \[at] COST\f[R]):-.IP \[bu] 2-\f[B]If an amount value begins with a plus sign:\f[R]-.PD 0-.P-.PD-that will be removed: \f[CR]+AMT\f[R] becomes \f[CR]AMT\f[R]-.IP \[bu] 2-\f[B]If an amount value is parenthesised:\f[R]-.PD 0-.P-.PD-it will be de\-parenthesised and sign\-flipped: \f[CR](AMT)\f[R] becomes-\f[CR]\-AMT\f[R]-.IP \[bu] 2-\f[B]If an amount value has two minus signs (or two sets of parentheses,-or a minus sign and parentheses):\f[R]-.PD 0-.P-.PD-they cancel out and will be removed: \f[CR]\-\-AMT\f[R] or-\f[CR]\-(AMT)\f[R] becomes \f[CR]AMT\f[R]-.IP \[bu] 2-\f[B]If an amount value contains just a sign (or just a set of-parentheses):\f[R]-.PD 0-.P-.PD-that is removed, making it an empty value.-\f[CR]\[dq]+\[dq]\f[R] or \f[CR]\[dq]\-\[dq]\f[R] or-\f[CR]\[dq]()\[dq]\f[R] becomes \f[CR]\[dq]\[dq]\f[R].-.PP-It\[aq]s not possible (without preprocessing the CSV) to set an amount-to its absolute value, ie discard its sign.-.SS Setting currency/commodity-If the currency/commodity symbol is included in the CSV\[aq]s amount-field(s):-.IP-.EX-2023\-01\-01,foo,$123.00-.EE-.PP-you don\[aq]t have to do anything special for the commodity symbol, it-will be assigned as part of the amount.-Eg:-.IP-.EX-fields date,description,amount-.EE-.IP-.EX-2023\-01\-01 foo-    expenses:unknown         $123.00-    income:unknown          $\-123.00-.EE-.PP-If the currency is provided as a separate CSV field:-.IP-.EX-2023\-01\-01,foo,USD,123.00-.EE-.PP-You can assign that to the \f[CR]currency\f[R] pseudo\-field, which has-the special effect of prepending itself to every amount in the-transaction (on the left, with no separating space):-.IP-.EX-fields date,description,currency,amount-.EE-.IP-.EX-2023\-01\-01 foo-    expenses:unknown       USD123.00-    income:unknown        USD\-123.00-.EE-.PP-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:-.IP-.EX-fields date,description,cur,amt-amount %amt %cur-.EE-.IP-.EX-2023\-01\-01 foo-    expenses:unknown        123.00 USD-    income:unknown         \-123.00 USD-.EE-.PP-Note we used a temporary field name (\f[CR]cur\f[R]) that is not-\f[CR]currency\f[R] \- that would trigger the prepending effect, which-we don\[aq]t want here.-.SS Amount decimal places-Like amounts in a journal file, the amounts generated by CSV rules like-\f[CR]amount1\f[R] influence commodity display styles, such as the-number of decimal places displayed in reports.-.PP-The original amounts as written in the CSV file do not affect display-style (because we don\[aq]t yet reliably know their commodity).-.SS Referencing other fields-In field assignments, you can interpolate only CSV fields, not hledger-fields.-In the example below, there\[aq]s both a CSV field and a hledger field-named amount1, but %amount1 always means the CSV field, not the hledger-field:-.IP-.EX-# Name the third CSV field \[dq]amount1\[dq]-fields date,description,amount1--# Set hledger\[aq]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-.EE-.PP-Here, since there\[aq]s no CSV amount1 field, %amount1 will produce a-literal \[dq]amount1\[dq]:-.IP-.EX-fields date,description,csvamount-amount1 %csvamount USD-# Can\[aq]t interpolate amount1 here-comment %amount1-.EE-.PP-When there are multiple field assignments to the same hledger field,-only the last one takes effect.-Here, comment\[aq]s value will be be B, or C if \[dq]something\[dq] is-matched, but never A:-.IP-.EX-comment A-comment B-if something- comment C-.EE-.SS How CSV rules are evaluated-Here\[aq]s how to think of CSV rules being evaluated (if you really need-to).-First,-.IP \[bu] 2-\f[CR]include\f[R] \- 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.)-.PP-Then \[dq]global\[dq] rules are evaluated, top to bottom.-If a rule is repeated, the last one wins:-.IP \[bu] 2-\f[CR]skip\f[R] (at top level)-.IP \[bu] 2-\f[CR]date\-format\f[R]-.IP \[bu] 2-\f[CR]newest\-first\f[R]-.IP \[bu] 2-\f[CR]fields\f[R] \- names the CSV fields, optionally sets up initial-assignments to hledger fields-.PP-Then for each CSV record in turn:-.IP \[bu] 2-test all \f[CR]if\f[R] blocks.-If any of them contain a \f[CR]end\f[R] rule, skip all remaining CSV-records.-Otherwise if any of them contain a \f[CR]skip\f[R] rule, skip that many-CSV records.-If there are multiple matched \f[CR]skip\f[R] rules, the first one wins.-.IP \[bu] 2-collect all field assignments at top level and in matched \f[CR]if\f[R]-blocks.-When there are multiple assignments for a field, keep only the last one.-.IP \[bu] 2-compute a value for each hledger field \- either the one that was-assigned to it (and interpolate the %CSVFIELD references), or a default-.IP \[bu] 2-generate a hledger transaction (journal entry) from these values.-.PP-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.-.PP-.SS Well factored rules-Some things than can help reduce duplication and complexity in rules-files:-.IP \[bu] 2-Extracting common rules usable with multiple CSV files into a-\f[CR]common.rules\f[R], and adding \f[CR]include common.rules\f[R] to-each CSV\[aq]s rules file.-.IP \[bu] 2-Splitting if blocks into smaller if blocks, extracting the frequently-used parts.-.SS CSV rules examples-.SS Bank of Ireland-Here\[aq]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:-.IP-.EX-Date,Details,Debit,Credit,Balance-07/12/2012,LODGMENT       529898,,10.0,131.21-07/12/2012,PAYMENT,5,,126-.EE-.IP-.EX-# 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 \[dq]balance\[dq]-# 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-.EE-.IP-.EX-$ 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-.EE-.PP-The balance assertions don\[aq]t raise an error above, because we\[aq]re-reading directly from CSV, but they will be checked if these entries are-imported into a journal file.-.SS Coinbase-A simple example with some CSV from Coinbase.-The spot price is recorded using cost notation.-The legacy \f[CR]amount\f[R] field name conveniently sets amount 2-(posting 2\[aq]s amount) to the total cost.-.IP-.EX-# 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,\[dq]\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]Received 100.00 USDC from an external account\[dq]-.EE-.IP-.EX-# 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 \[at] %Spot_Price_at_Transaction %Spot_Price_Currency-.EE-.IP-.EX-$ hledger print \-f coinbase.csv-2021\-12\-30 Received 100.00 USDC from an external account-    assets:coinbase:cc    100 USDC \[at] 0.740000 GBP-    income:unknown                 \-74.000000 GBP-.EE-.SS Amazon-Here we convert amazon.com order history, and use an if block to-generate a third posting if there\[aq]s a fee.-(In practice you\[aq]d probably get this data from your bank instead,-but it\[aq]s an example.)-.IP-.EX-\[dq]Date\[dq],\[dq]Type\[dq],\[dq]To/From\[dq],\[dq]Name\[dq],\[dq]Status\[dq],\[dq]Amount\[dq],\[dq]Fees\[dq],\[dq]Transaction ID\[dq]-\[dq]Jul 29, 2012\[dq],\[dq]Payment\[dq],\[dq]To\[dq],\[dq]Foo.\[dq],\[dq]Completed\[dq],\[dq]$20.00\[dq],\[dq]$0.00\[dq],\[dq]16000000000000DGLNJPI1P9B8DKPVHL\[dq]-\[dq]Jul 30, 2012\[dq],\[dq]Payment\[dq],\[dq]To\[dq],\[dq]Adapteva, Inc.\[dq],\[dq]Completed\[dq],\[dq]$25.00\[dq],\[dq]$1.00\[dq],\[dq]17LA58JSKRD4HDGLNJPI1P9B8DKPVHL\[dq]-.EE-.IP-.EX-# amazon\-orders.csv.rules--# skip one header line-skip 1--# name the csv fields, and assign the transaction\[aq]s date, amount and code.-# Avoided the \[dq]status\[dq] and \[dq]amount\[dq] 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\[aq]m assuming amzamount excludes the fees, don\[aq]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-.EE-.IP-.EX-$ 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-.EE-.SS Paypal-Here\[aq]s a real\-world rules file for (customised) Paypal CSV, with-some Paypal\-specific rules, and a second rules file included:-.IP-.EX-\[dq]Date\[dq],\[dq]Time\[dq],\[dq]TimeZone\[dq],\[dq]Name\[dq],\[dq]Type\[dq],\[dq]Status\[dq],\[dq]Currency\[dq],\[dq]Gross\[dq],\[dq]Fee\[dq],\[dq]Net\[dq],\[dq]From Email Address\[dq],\[dq]To Email Address\[dq],\[dq]Transaction ID\[dq],\[dq]Item Title\[dq],\[dq]Item ID\[dq],\[dq]Reference Txn ID\[dq],\[dq]Receipt ID\[dq],\[dq]Balance\[dq],\[dq]Note\[dq]-\[dq]10/01/2019\[dq],\[dq]03:46:20\[dq],\[dq]PDT\[dq],\[dq]Calm Radio\[dq],\[dq]Subscription Payment\[dq],\[dq]Completed\[dq],\[dq]USD\[dq],\[dq]\-6.99\[dq],\[dq]0.00\[dq],\[dq]\-6.99\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]memberships\[at]calmradio.com\[dq],\[dq]60P57143A8206782E\[dq],\[dq]MONTHLY \- $1 for the first 2 Months: Me \- Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month\[dq],\[dq]\[dq],\[dq]I\-R8YLY094FJYR\[dq],\[dq]\[dq],\[dq]\-6.99\[dq],\[dq]\[dq]-\[dq]10/01/2019\[dq],\[dq]03:46:20\[dq],\[dq]PDT\[dq],\[dq]\[dq],\[dq]Bank Deposit to PP Account \[dq],\[dq]Pending\[dq],\[dq]USD\[dq],\[dq]6.99\[dq],\[dq]0.00\[dq],\[dq]6.99\[dq],\[dq]\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]0TU1544T080463733\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]60P57143A8206782E\[dq],\[dq]\[dq],\[dq]0.00\[dq],\[dq]\[dq]-\[dq]10/01/2019\[dq],\[dq]08:57:01\[dq],\[dq]PDT\[dq],\[dq]Patreon\[dq],\[dq]PreApproved Payment Bill User Payment\[dq],\[dq]Completed\[dq],\[dq]USD\[dq],\[dq]\-7.00\[dq],\[dq]0.00\[dq],\[dq]\-7.00\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]support\[at]patreon.com\[dq],\[dq]2722394R5F586712G\[dq],\[dq]Patreon* Membership\[dq],\[dq]\[dq],\[dq]B\-0PG93074E7M86381M\[dq],\[dq]\[dq],\[dq]\-7.00\[dq],\[dq]\[dq]-\[dq]10/01/2019\[dq],\[dq]08:57:01\[dq],\[dq]PDT\[dq],\[dq]\[dq],\[dq]Bank Deposit to PP Account \[dq],\[dq]Pending\[dq],\[dq]USD\[dq],\[dq]7.00\[dq],\[dq]0.00\[dq],\[dq]7.00\[dq],\[dq]\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]71854087RG994194F\[dq],\[dq]Patreon* Membership\[dq],\[dq]\[dq],\[dq]2722394R5F586712G\[dq],\[dq]\[dq],\[dq]0.00\[dq],\[dq]\[dq]-\[dq]10/19/2019\[dq],\[dq]03:02:12\[dq],\[dq]PDT\[dq],\[dq]Wikimedia Foundation, Inc.\[dq],\[dq]Subscription Payment\[dq],\[dq]Completed\[dq],\[dq]USD\[dq],\[dq]\-2.00\[dq],\[dq]0.00\[dq],\[dq]\-2.00\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]tle\[at]wikimedia.org\[dq],\[dq]K9U43044RY432050M\[dq],\[dq]Monthly donation to the Wikimedia Foundation\[dq],\[dq]\[dq],\[dq]I\-R5C3YUS3285L\[dq],\[dq]\[dq],\[dq]\-2.00\[dq],\[dq]\[dq]-\[dq]10/19/2019\[dq],\[dq]03:02:12\[dq],\[dq]PDT\[dq],\[dq]\[dq],\[dq]Bank Deposit to PP Account \[dq],\[dq]Pending\[dq],\[dq]USD\[dq],\[dq]2.00\[dq],\[dq]0.00\[dq],\[dq]2.00\[dq],\[dq]\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]3XJ107139A851061F\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]K9U43044RY432050M\[dq],\[dq]\[dq],\[dq]0.00\[dq],\[dq]\[dq]-\[dq]10/22/2019\[dq],\[dq]05:07:06\[dq],\[dq]PDT\[dq],\[dq]Noble Benefactor\[dq],\[dq]Subscription Payment\[dq],\[dq]Completed\[dq],\[dq]USD\[dq],\[dq]10.00\[dq],\[dq]\-0.59\[dq],\[dq]9.41\[dq],\[dq]noble\[at]bene.fac.tor\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]6L8L1662YP1334033\[dq],\[dq]Joyful Systems\[dq],\[dq]\[dq],\[dq]I\-KC9VBGY2GWDB\[dq],\[dq]\[dq],\[dq]9.41\[dq],\[dq]\[dq]-.EE-.IP-.EX-# paypal\-custom.csv.rules--# Tips:-# Export from Activity \-> Statements \-> Custom \-> Activity download-# Suggested transaction type: \[dq]Balance affecting\[dq]-# Paypal\[aq]s default fields in 2018 were:-# \[dq]Date\[dq],\[dq]Time\[dq],\[dq]TimeZone\[dq],\[dq]Name\[dq],\[dq]Type\[dq],\[dq]Status\[dq],\[dq]Currency\[dq],\[dq]Gross\[dq],\[dq]Fee\[dq],\[dq]Net\[dq],\[dq]From Email Address\[dq],\[dq]To Email Address\[dq],\[dq]Transaction ID\[dq],\[dq]Shipping Address\[dq],\[dq]Address Status\[dq],\[dq]Item Title\[dq],\[dq]Item ID\[dq],\[dq]Shipping and Handling Amount\[dq],\[dq]Insurance Amount\[dq],\[dq]Sales Tax\[dq],\[dq]Option 1 Name\[dq],\[dq]Option 1 Value\[dq],\[dq]Option 2 Name\[dq],\[dq]Option 2 Value\[dq],\[dq]Reference Txn ID\[dq],\[dq]Invoice Number\[dq],\[dq]Custom Number\[dq],\[dq]Quantity\[dq],\[dq]Receipt ID\[dq],\[dq]Balance\[dq],\[dq]Address Line 1\[dq],\[dq]Address Line 2/District/Neighborhood\[dq],\[dq]Town/City\[dq],\[dq]State/Province/Region/County/Territory/Prefecture/Republic\[dq],\[dq]Zip/Postal Code\[dq],\[dq]Country\[dq],\[dq]Contact Phone Number\[dq],\[dq]Subject\[dq],\[dq]Note\[dq],\[dq]Country Code\[dq],\[dq]Balance Impact\[dq]-# This rules file assumes the following more detailed fields, configured in \[dq]Customize report fields\[dq]:-# \[dq]Date\[dq],\[dq]Time\[dq],\[dq]TimeZone\[dq],\[dq]Name\[dq],\[dq]Type\[dq],\[dq]Status\[dq],\[dq]Currency\[dq],\[dq]Gross\[dq],\[dq]Fee\[dq],\[dq]Net\[dq],\[dq]From Email Address\[dq],\[dq]To Email Address\[dq],\[dq]Transaction ID\[dq],\[dq]Item Title\[dq],\[dq]Item ID\[dq],\[dq]Reference Txn ID\[dq],\[dq]Receipt ID\[dq],\[dq]Balance\[dq],\[dq]Note\[dq]--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\[aq]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\[aq]s income (a debit)-if %grossamount \[ha][\[ha]\-]- account2 income:unknown-# if negative, it\[aq]s an expense (a credit)-if %grossamount \[ha]\-- 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-.EE-.IP-.EX-# 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-.EE-.IP-.EX-$ 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\[at]joyful.com, toemail:memberships\[at]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\[at]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\[at]joyful.com, toemail:support\[at]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\[at]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\[at]joyful.com, toemail:tle\[at]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\[at]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\[at]bene.fac.tor, toemail:simon\[at]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:-.EE-.SH Timeclock-The time logging format of timeclock.el, as read by hledger.-.PP-hledger can read time logs in timeclock format.-As with Ledger, these are (a subset of) timeclock.el\[aq]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 \f[CR]#\f[R] or \f[CR];\f[R] or \f[CR]*\f[R], and-blank lines, are ignored.-.IP-.EX-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-.EE-.PP-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, \f[CR]hledger print\f[R] generates these journal-entries:-.IP-.EX-$ 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-.EE-.PP-Here is a sample.timeclock to download and some queries to try:-.IP-.EX-$ 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-.EE-.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-.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]-.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.-These rely on a \[dq]timeclock\[dq] executable which I think is just the-ledger 2 executable renamed.-.PP-.SH Timedot-\f[CR]timedot\f[R] format is hledger\[aq]s human\-friendly time logging-format.-Compared to \f[CR]timeclock\f[R] 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:-.IP-.EX-2023\-05\-01-hom:errands          .... ....  ; two hours; the space is ignored-fos:hledger:timedot  ..         ; half an hour-per:admin:finance               ; no time spent yet-.EE-.PP-hledger reads this as a transaction on this day with three (unbalanced)-postings, where each dot represents \[dq]0.25\[dq].-No commodity symbol is assumed, but we typically interpret it as hours.-.IP-.EX-$ 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-.EE-.PP-A timedot file contains a series of transactions (usually one per day).-Each begins with a \f[B]simple date\f[R] (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.-.PP-After the date line are zero or more time postings, consisting of:-.IP \[bu] 2-\f[B]An account name\f[R] \- any hledger\-style account name, optionally-indented.-.IP \[bu] 2-\f[B]Two or more spaces\f[R] \- required if there is an amount (as in-journal format).-.IP \[bu] 2-\f[B]A timedot amount\f[R], which can be-.RS 2-.IP \[bu] 2-empty (representing zero)-.IP \[bu] 2-a number, optionally followed by a unit \f[CR]s\f[R], \f[CR]m\f[R],-\f[CR]h\f[R], \f[CR]d\f[R], \f[CR]w\f[R], \f[CR]mo\f[R], or-\f[CR]y\f[R], 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.-.IP \[bu] 2-one or more dots (period characters), each representing 0.25.-These are the dots in \[dq]timedot\[dq].-Spaces are ignored and can be used for grouping/alignment.-.IP \[bu] 2-\f[I]Added in 1.32\f[R] one or more letters.-These are like dots but they also generate a tag \f[CR]t:\f[R] (short-for \[dq]type\[dq]) 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 \f[CR]\-\-pivot t\f[R].-.RE-.IP \[bu] 2-\f[B]An optional comment\f[R] following a semicolon (a hledger\-style-posting comment).-.PP-There is some flexibility to help with keeping time log data and notes-in the same file:-.IP \[bu] 2-Blank lines and lines beginning with \f[CR]#\f[R] or \f[CR];\f[R] are-ignored.-.IP \[bu] 2-After the first date line, lines which do not contain a double space are-parsed as postings with zero amount.-(hledger\[aq]s register reports will show these if you add \-E).-.IP \[bu] 2-Before the first date line, lines beginning with \f[CR]*\f[R] (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 \f[CR]*\f[R]\[aq]s followed by a space)-will be ignored.-This means the time log can also be a org outline.-.SS Timedot examples-Numbers:-.IP-.EX-2016/2/3-inc:client1   4-fos:hledger   3h-biz:research  60m-.EE-.PP-Dots:-.IP-.EX-# 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  .-.EE-.IP-.EX-$ hledger \-f a.timedot print date:2016/2/2-2016\-02\-02 *-    (inc:client1)          2.00--2016\-02\-02 *-    (biz:research)          0.25-.EE-.IP-.EX-$ 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 -.EE-.PP-Letters:-.IP-.EX-# Activity types:-#  c cleanup/catchup/repair-#  e enhancement-#  s support-#  l learning/research--2023\-11\-01-work:adm  ccecces-.EE-.IP-.EX-$ 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-.EE-.IP-.EX-$ hledger \-f a.timedot bal-                1.75  work:adm-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--                1.75  -.EE-.IP-.EX-$ hledger \-f a.timedot bal \-\-pivot t-                1.00  c-                0.50  e-                0.25  s-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--                1.75  -.EE-.PP-Org:-.IP-.EX-* 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-.EE-.PP-Using \f[CR].\f[R] as account name separator:-.IP-.EX-2016/2/4-fos.hledger.timedot  4h-fos.ledger           ..-.EE-.IP-.EX-$ hledger \-f a.timedot \-\-alias \[aq]/\[rs]./=:\[aq] bal \-t-                4.50  fos-                4.00    hledger:timedot-                0.50    ledger-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--                4.50-.EE-.SH PART 3: REPORTING CONCEPTS-.SH Amount formatting-.SS 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:-.PP-First, if there\[aq]s a \f[CR]D\f[R] directive declaring a default-commodity, that commodity symbol and amount format is applied to all-no\-symbol amounts in the journal.-.PP-Then each commodity\[aq]s display style is determined from its-\f[CR]commodity\f[R] directive.-We recommend always declaring commodities with \f[CR]commodity\f[R]-directives, since they help ensure consistent display styles and-precisions, and bring other benefits such as error checking for-commodity symbols.-Here\[aq]s an example:-.IP-.EX-# 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-.EE-.PP-But for convenience, if a \f[CR]commodity\f[R] directive is not present,-hledger infers a commodity\[aq]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-.IP \[bu] 2-the symbol placement and decimal mark of the first amount seen-.IP \[bu] 2-the digit group marks of the first amount with digit group marks-.IP \[bu] 2-and the maximum number of decimal digits seen across all amounts.-.PP-And as fallback if no applicable amounts are found, it would use a-default style, like \f[CR]$1000.00\f[R] (symbol on the left with no-space, period as decimal mark, and two decimal digits).-.PP-Finally, commodity styles can be overridden by the-\f[CR]\-c/\-\-commodity\-style\f[R] command line option.-.SS 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\[aq]s rounding (it rounds to the-nearest even digit).-So eg 0.5 displayed with zero decimal digits appears as \[dq]0\[dq].-.SS Trailing decimal marks-If you\[aq]re wondering why your \f[CR]print\f[R] 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:-.IP-.EX-commodity $1,000.00--2023\-01\-02-    (a)      $1000-.EE-.IP-.EX-$ hledger print-2023\-01\-02-    (a)        $1,000.-.EE-.PP-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):-.IP-.EX-$ hledger print \-c \[aq]$1000.00\[aq]-2023\-01\-02-    (a)          $1000-.EE-.PP-or by forcing print to always show decimal digits, with \-\-round:-.IP-.EX-$ hledger print \-c \[aq]$1,000.00\[aq] \-\-round=soft-2023\-01\-02-    (a)      $1,000.00-.EE-.SS Amount parseability-More generally, hledger output falls into three rough categories, which-format amounts a little bit differently to suit different consumers:-.PP-\f[B]1.-\[dq]hledger\-readable output\[dq] \- should be readable by hledger (and-by humans)\f[R]-.IP \[bu] 2-This is produced by reports that show full journal entries:-\f[CR]print\f[R], \f[CR]import\f[R], \f[CR]close\f[R],-\f[CR]rewrite\f[R] etc.-.IP \[bu] 2-It shows amounts with their original journal precisions, which may not-be consistent.-.IP \[bu] 2-It adds a trailing decimal mark when needed to avoid showing ambiguous-amounts.-.IP \[bu] 2-It can be parsed reliably (by hledger and ledger2beancount at least, but-perhaps not by Ledger..)-.PP-\f[B]2.-\[dq]human\-readable output\[dq] \- usually for humans\f[R]-.IP \[bu] 2-This is produced by all other reports.-.IP \[bu] 2-It shows amounts with standard display precisions, which will be-consistent within each commodity.-.IP \[bu] 2-It shows ambiguous amounts unmodified.-.IP \[bu] 2-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).-.PP-\f[B]3.-\[dq]machine\-readable output\[dq] \- usually for other software\f[R]-.IP \[bu] 2-This is produced by all reports when an output format like-\f[CR]csv\f[R], \f[CR]tsv\f[R], \f[CR]json\f[R], or \f[CR]sql\f[R] is-selected.-.IP \[bu] 2-It shows amounts as 1 or 2 do, but without digit group marks.-.IP \[bu] 2-It can be parsed reliably (if needed, the decimal mark can be changed-with \-c/\-\-commodity\-style).-.SH Time periods-.SS Report start & end date-By default, most hledger reports will show the full span of time-represented by the journal.-The report start date will be the earliest transaction or posting date,-and the report end date will be the latest transaction, posting, or-market price date.-.PP-Often you will want to see a shorter time span, such as the current-month.-You can specify a start and/or end date using \f[CR]\-b/\-\-begin\f[R],-\f[CR]\-e/\-\-end\f[R], \f[CR]\-p/\-\-period\f[R] or a \f[CR]date:\f[R]-query (described below).-All of these accept the smart date syntax (below).-.PP-Some notes:-.IP \[bu] 2-End dates are exclusive, as in Ledger, so you should write the date-\f[I]after\f[R] the last day you want to see in the report.-.IP \[bu] 2-As noted in reporting options: among start/end dates specified with-\f[I]options\f[R], the last (i.e.-right\-most) option takes precedence.-.IP \[bu] 2-The effective report start and end dates are the intersection of the-start/end dates from options and that from \f[CR]date:\f[R] queries.-That is, \f[CR]date:2019\-01 date:2019 \-p\[aq]2000 to 2030\[aq]\f[R]-yields January 2019, the smallest common time span.-.IP \[bu] 2-In some cases a report interval will adjust start/end dates to fall on-interval boundaries (see below).-.PP-Examples:-.PP-.TS-tab(@);-lw(12.4n) lw(57.6n).-T{-\f[CR]\-b 2016/3/17\f[R]-T}@T{-begin on St.\ Patrick\[cq]s day 2016-T}-T{-\f[CR]\-e 12/1\f[R]-T}@T{-end at the start of december 1st of the current year (11/30 will be the-last date included)-T}-T{-\f[CR]\-b thismonth\f[R]-T}@T{-all transactions on or after the 1st of the current month-T}-T{-\f[CR]\-p thismonth\f[R]-T}@T{-all transactions in the current month-T}-T{-\f[CR]date:2016/3/17..\f[R]-T}@T{-the above written as queries instead (\f[CR]..\f[R] can also be replaced-with \f[CR]\-\f[R])-T}-T{-\f[CR]date:..12/1\f[R]-T}@T{-T}-T{-\f[CR]date:thismonth..\f[R]-T}@T{-T}-T{-\f[CR]date:thismonth\f[R]-T}@T{-T}-.TE-.SS Smart dates-hledger\[aq]s user interfaces accept a \[dq]smart date\[dq] syntax for-added convenience.-Smart dates optionally can be relative to today\[aq]s date, be written-with english words, and have less\-significant parts omitted (missing-parts are inferred as 1).-Some examples:-.PP-.TS-tab(@);-lw(24.2n) lw(45.8n).-T{-\f[CR]2004/10/1\f[R], \f[CR]2004\-01\-01\f[R], \f[CR]2004.9.1\f[R]-T}@T{-exact date, several separators allowed.-Year is 4+ digits, month is 1\-12, day is 1\-31-T}-T{-\f[CR]2004\f[R]-T}@T{-start of year-T}-T{-\f[CR]2004/10\f[R]-T}@T{-start of month-T}-T{-\f[CR]10/1\f[R]-T}@T{-month and day in current year-T}-T{-\f[CR]21\f[R]-T}@T{-day in current month-T}-T{-\f[CR]october, oct\f[R]-T}@T{-start of month in current year-T}-T{-\f[CR]yesterday, today, tomorrow\f[R]-T}@T{-\-1, 0, 1 days from today-T}-T{-\f[CR]last/this/next day/week/month/quarter/year\f[R]-T}@T{-\-1, 0, 1 periods from the current period-T}-T{-\f[CR]in n days/weeks/months/quarters/years\f[R]-T}@T{-n periods from the current period-T}-T{-\f[CR]n days/weeks/months/quarters/years ahead\f[R]-T}@T{-n periods from the current period-T}-T{-\f[CR]n days/weeks/months/quarters/years ago\f[R]-T}@T{-\-n periods from the current period-T}-T{-\f[CR]20181201\f[R]-T}@T{-8 digit YYYYMMDD with valid year month and day-T}-T{-\f[CR]201812\f[R]-T}@T{-6 digit YYYYMM with valid year and month-T}-.TE-.PP-Some counterexamples \- malformed digit sequences might give surprising-results:-.PP-.TS-tab(@);-lw(11.4n) lw(58.6n).-T{-\f[CR]201813\f[R]-T}@T{-6 digits with an invalid month is parsed as start of 6\-digit year-T}-T{-\f[CR]20181301\f[R]-T}@T{-8 digits with an invalid month is parsed as start of 8\-digit year-T}-T{-\f[CR]20181232\f[R]-T}@T{-8 digits with an invalid day gives an error-T}-T{-\f[CR]201801012\f[R]-T}@T{-9+ digits beginning with a valid YYYYMMDD gives an error-T}-.TE-.PP-\[dq]Today\[aq]s date\[dq] can be overridden with the-\f[CR]\-\-today\f[R] option, in case it\[aq]s needed for testing or for-recreating old reports.-(Except for periodic transaction rules, which are not affected by-\f[CR]\-\-today\f[R].)-.SS 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.-.PP-The following standard intervals can be enabled with command\-line-flags:-.IP \[bu] 2-\f[CR]\-D/\-\-daily\f[R]-.IP \[bu] 2-\f[CR]\-W/\-\-weekly\f[R]-.IP \[bu] 2-\f[CR]\-M/\-\-monthly\f[R]-.IP \[bu] 2-\f[CR]\-Q/\-\-quarterly\f[R]-.IP \[bu] 2-\f[CR]\-Y/\-\-yearly\f[R]-.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:-.IP \[bu] 2-an inferred start date will be adjusted earlier if needed to fall on a-natural period boundary-.IP \[bu] 2-an inferred end date will be adjusted later if needed to make the last-period the same length as the others.-.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.-.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-report interval.-.PP-Here\[aq]s a period expression with a start and end date (specifying the-first quarter of 2009):-.PP-.TS-tab(@);-l.-T{-\f[CR]\-p \[dq]from 2009/1/1 to 2009/4/1\[dq]\f[R]-T}-.TE-.PP-Several keywords like \[dq]from\[dq] and \[dq]to\[dq] are supported for-readability; these are optional.-\[dq]to\[dq] can also be written as \[dq]..\[dq] or \[dq]\-\[dq].-The spaces are also optional, as long as you don\[aq]t run two dates-together.-So the following are equivalent to the above:-.PP-.TS-tab(@);-l.-T{-\f[CR]\-p \[dq]2009/1/1 2009/4/1\[dq]\f[R]-T}-T{-\f[CR]\-p2009/1/1to2009/4/1\f[R]-T}-T{-\f[CR]\-p2009/1/1..2009/4/1\f[R]-T}-.TE-.PP-Dates are smart dates, so if the current year is 2009, these are also-equivalent to the above:-.PP-.TS-tab(@);-l.-T{-\f[CR]\-p \[dq]1/1 4/1\[dq]\f[R]-T}-T{-\f[CR]\-p \[dq]jan\-apr\[dq]\f[R]-T}-T{-\f[CR]\-p \[dq]this year to 4/1\[dq]\f[R]-T}-.TE-.PP-If you specify only one date, the missing start or end date will be the-earliest or latest transaction date in the journal:-.PP-.TS-tab(@);-l l.-T{-\f[CR]\-p \[dq]from 2009/1/1\[dq]\f[R]-T}@T{-everything after january 1, 2009-T}-T{-\f[CR]\-p \[dq]since 2009/1\[dq]\f[R]-T}@T{-the same, since is a synonym-T}-T{-\f[CR]\-p \[dq]from 2009\[dq]\f[R]-T}@T{-the same-T}-T{-\f[CR]\-p \[dq]to 2009\[dq]\f[R]-T}@T{-everything before january 1, 2009-T}-.TE-.PP-You can also specify a period by writing a single partial or full date:-.PP-.TS-tab(@);-lw(14.5n) lw(55.5n).-T{-\f[CR]\-p \[dq]2009\[dq]\f[R]-T}@T{-the year 2009; equivalent to \[lq]2009/1/1 to 2010/1/1\[rq]-T}-T{-\f[CR]\-p \[dq]2009/1\[dq]\f[R]-T}@T{-the month of january 2009; equivalent to \[lq]2009/1/1 to 2009/2/1\[rq]-T}-T{-\f[CR]\-p \[dq]2009/1/1\[dq]\f[R]-T}@T{-the first day of 2009; equivalent to \[lq]2009/1/1 to 2009/1/2\[rq]-T}-.TE-.PP-or by using the \[dq]Q\[dq] quarter\-year syntax (case insensitive):-.PP-.TS-tab(@);-lw(15.3n) lw(54.7n).-T{-\f[CR]\-p \[dq]2009Q1\[dq]\f[R]-T}@T{-first quarter of 2009, equivalent to \[lq]2009/1/1 to 2009/4/1\[rq]-T}-T{-\f[CR]\-p \[dq]q4\[dq]\f[R]-T}@T{-fourth quarter of the current year-T}-.TE-.SS 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 \f[CR]in\f[R]:-.PP-.TS-tab(@);-l.-T{-\f[CR]\-p \[dq]weekly from 2009/1/1 to 2009/4/1\[dq]\f[R]-T}-T{-\f[CR]\-p \[dq]monthly in 2008\[dq]\f[R]-T}-T{-\f[CR]\-p \[dq]quarterly\[dq]\f[R]-T}-.TE-.SS More complex report intervals-Some more complex intervals can be specified within period expressions,-such as:-.IP \[bu] 2-\f[CR]biweekly\f[R] (every two weeks)-.IP \[bu] 2-\f[CR]fortnightly\f[R]-.IP \[bu] 2-\f[CR]bimonthly\f[R] (every two months)-.IP \[bu] 2-\f[CR]every day|week|month|quarter|year\f[R]-.IP \[bu] 2-\f[CR]every N days|weeks|months|quarters|years\f[R]-.PP-Weekly on a custom day:-.IP \[bu] 2-\f[CR]every Nth day of week\f[R] (\f[CR]th\f[R], \f[CR]nd\f[R],-\f[CR]rd\f[R], or \f[CR]st\f[R] are all accepted after the number)-.IP \[bu] 2-\f[CR]every WEEKDAYNAME\f[R] (full or three\-letter english weekday-name, case insensitive)-.PP-Monthly on a custom day:-.IP \[bu] 2-\f[CR]every Nth day [of month]\f[R]-.IP \[bu] 2-\f[CR]every Nth WEEKDAYNAME [of month]\f[R]-.PP-Yearly on a custom day:-.IP \[bu] 2-\f[CR]every MM/DD [of year]\f[R] (month number and day of month number)-.IP \[bu] 2-\f[CR]every MONTHNAME DDth [of year]\f[R] (full or three\-letter english-month name, case insensitive, and day of month number)-.IP \[bu] 2-\f[CR]every DDth MONTHNAME [of year]\f[R] (equivalent to the above)-.PP-Examples:-.PP-.TS-tab(@);-lw(26.8n) lw(43.2n).-T{-\f[CR]\-p \[dq]bimonthly from 2008\[dq]\f[R]-T}@T{-T}-T{-\f[CR]\-p \[dq]every 2 weeks\[dq]\f[R]-T}@T{-T}-T{-\f[CR]\-p \[dq]every 5 months from 2009/03\[dq]\f[R]-T}@T{-T}-T{-\f[CR]\-p \[dq]every 2nd day of week\[dq]\f[R]-T}@T{-periods will go from Tue to Tue-T}-T{-\f[CR]\-p \[dq]every Tue\[dq]\f[R]-T}@T{-same-T}-T{-\f[CR]\-p \[dq]every 15th day\[dq]\f[R]-T}@T{-period boundaries will be on 15th of each month-T}-T{-\f[CR]\-p \[dq]every 2nd Monday\[dq]\f[R]-T}@T{-period boundaries will be on second Monday of each month-T}-T{-\f[CR]\-p \[dq]every 11/05\[dq]\f[R]-T}@T{-yearly periods with boundaries on 5th of November-T}-T{-\f[CR]\-p \[dq]every 5th November\[dq]\f[R]-T}@T{-same-T}-T{-\f[CR]\-p \[dq]every Nov 5th\[dq]\f[R]-T}@T{-same-T}-.TE-.PP-Show historical balances at end of the 15th day of each month (N is an-end date, exclusive as always):-.IP-.EX-$ hledger balance \-H \-p \[dq]every 16th day\[dq]-.EE-.PP-Group postings from the start of wednesday to end of the following-tuesday (N is both (inclusive) start date and (exclusive) end date):-.IP-.EX-$ hledger register checking \-p \[dq]every 3rd day of week\[dq]-.EE-.SS Multiple weekday intervals-This special form is also supported:-.IP \[bu] 2-\f[CR]every WEEKDAYNAME,WEEKDAYNAME,...\f[R] (full or three\-letter-english weekday names, case insensitive)-.PP-Also, \f[CR]weekday\f[R] and \f[CR]weekendday\f[R] are shorthand for-\f[CR]mon,tue,wed,thu,fri\f[R] and \f[CR]sat,sun\f[R].-.PP-This is mainly intended for use with \f[CR]\-\-forecast\f[R], to-generate periodic transactions on arbitrary days of the week.-It may be less useful with \f[CR]\-p\f[R], since it divides each week-into subperiods of unequal length, which is unusual.-(Related: #1632)-.PP-Examples:-.PP-.TS-tab(@);-lw(17.8n) lw(52.2n).-T{-\f[CR]\-p \[dq]every mon,wed,fri\[dq]\f[R]-T}@T{-dates will be Mon, Wed, Fri; periods will be Mon\-Tue, Wed\-Thu,-Fri\-Sun-T}-T{-\f[CR]\-p \[dq]every weekday\[dq]\f[R]-T}@T{-dates will be Mon, Tue, Wed, Thu, Fri; periods will be Mon, Tue, Wed,-Thu, Fri\-Sun-T}-T{-\f[CR]\-p \[dq]every weekendday\[dq]\f[R]-T}@T{-dates will be Sat, Sun; periods will be Sat, Sun\-Fri-T}-.TE-.SH Depth-With the \f[CR]\-\-depth NUM\f[R] option (short form: \f[CR]\-NUM\f[R]),-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 \f[CR]depth:\f[R] query argument:-\f[CR]depth:2\f[R], \f[CR]\-\-depth=2\f[R] or \f[CR]\-2\f[R] are-equivalent.-.SH Queries-One of hledger\[aq]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.-.IP \[bu] 2-By default, a query term is interpreted as a case\-insensitive substring-pattern for matching account names:-.RS 2-.PP-\f[CR]car:fuel\f[R]-.PD 0-.P-.PD-\f[CR]dining groceries\f[R]-.PD 0-.P-.PD-.RE-.IP \[bu] 2-Patterns containing spaces or other special characters must be enclosed-in single or double quotes:-.RS 2-.PP-\f[CR]\[aq]personal care\[aq]\f[R]-.PD 0-.P-.PD-.RE-.IP \[bu] 2-These patterns are actually regular expressions, so you can add regexp-metacharacters for more precision (see \[dq]Regular expressions\[dq]-above for details):-.RS 2-.PP-\f[CR]\[aq]\[ha]expenses\[rs]b\[aq]\f[R]-.PD 0-.P-.PD-\f[CR]\[aq]food$\[aq]\f[R]-.PD 0-.P-.PD-\f[CR]\[aq]fuel|repair\[aq]\f[R]-.PD 0-.P-.PD-\f[CR]\[aq]accounts (payable|receivable)\[aq]\f[R]-.PD 0-.P-.PD-.RE-.IP \[bu] 2-To match something other than account name, add one of the query type-prefixes described in \[dq]Query types\[dq] below:-.RS 2-.PP-\f[CR]date:202312\-\f[R]-.PD 0-.P-.PD-\f[CR]status:\f[R]-.PD 0-.P-.PD-\f[CR]desc:amazon\f[R]-.PD 0-.P-.PD-\f[CR]cur:USD\f[R]-.PD 0-.P-.PD-\f[CR]cur:\[rs]\[rs]$\f[R]-.PD 0-.P-.PD-\f[CR]amt:\[aq]>0\[aq]\f[R]-.PD 0-.P-.PD-.RE-.IP \[bu] 2-Add a \f[CR]not:\f[R] prefix to negate a term:-.RS 2-.PP-\f[CR]not:status:\[aq]*\[aq]\f[R]-.PD 0-.P-.PD-\f[CR]not:desc:\[aq]opening|closing\[aq]\f[R]-.PD 0-.P-.PD-\f[CR]not:cur:USD\f[R]-.PD 0-.P-.PD-.RE-.IP \[bu] 2-Terms with different types are AND\-ed, terms with the same type are-OR\-ed (mostly; see \[dq]Combining query terms\[dq] below).-The following query:-.RS 2-.PP-\f[CR]date:2022 desc:amazon desc:amzn\f[R]-.PP-is interpreted as:-.PP-\f[I]date is in 2022 AND ( transaction description contains-\[dq]amazon\[dq] OR \[dq]amzn\[dq] )\f[R]-.RE-.SS Query types-Here are the types of query term available.-Remember these can also be prefixed with \f[B]\f[CB]not:\f[B]\f[R] to-convert them into a negative match.-.PP-\f[B]\f[CB]acct:REGEX\f[B]\f[R] or \f[B]\f[CB]REGEX\f[B]\f[R]-.PD 0-.P-.PD-Match account names containing this case insensitive regular expression.-This is the default query type, so we usually don\[aq]t bother writing-the \[dq]acct:\[dq] prefix.-.PP-\f[B]\f[CB]amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N\f[B]\f[R]-.PD 0-.P-.PD-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.-.PP-\f[B]\f[CB]code:REGEX\f[B]\f[R]-.PD 0-.P-.PD-Match by transaction code (eg check number).-.PP-\f[B]\f[CB]cur:REGEX\f[B]\f[R]-.PD 0-.P-.PD-Match postings or transactions including any amounts whose-currency/commodity symbol is fully matched by REGEX.-(For a partial match, use \f[CR].*REGEX.*\f[R]).-Note, to match special characters which are regex\-significant, you need-to escape them with \f[CR]\[rs]\f[R].-And for characters which are significant to your shell you may need one-more level of escaping.-So eg to match the dollar sign:-.PD 0-.P-.PD-\f[CR]hledger print cur:\[rs]\[rs]$\f[R].-.PP-\f[B]\f[CB]desc:REGEX\f[B]\f[R]-.PD 0-.P-.PD-Match transaction descriptions.-.PP-\f[B]\f[CB]date:PERIODEXPR\f[B]\f[R]-.PD 0-.P-.PD-Match dates (or with the \f[CR]\-\-date2\f[R] flag, secondary dates)-within the specified period.-PERIODEXPR is a period expression with no report interval.-Examples:-.PD 0-.P-.PD-\f[CR]date:2016\f[R], \f[CR]date:thismonth\f[R],-\f[CR]date:2/1\-2/15\f[R], \f[CR]date:2021\-07\-27..nextquarter\f[R].-.PP-\f[B]\f[CB]date2:PERIODEXPR\f[B]\f[R]-.PD 0-.P-.PD-Match secondary dates within the specified period (independent of the-\f[CR]\-\-date2\f[R] flag).-.PP-\f[B]\f[CB]depth:N\f[B]\f[R]-.PD 0-.P-.PD-Match (or display, depending on command) accounts at or above this-depth.-.PP-\f[B]\f[CB]expr:\[dq]TERM AND NOT (TERM OR TERM)\[dq]\f[B]\f[R] (eg)-.PD 0-.P-.PD-Match with a boolean combination of queries (which must be enclosed in-quotes).-See Combining query terms below.-.PP-\f[B]\f[CB]note:REGEX\f[B]\f[R]-.PD 0-.P-.PD-Match transaction notes (the part of the description right of-\f[CR]|\f[R], or the whole description if there\[aq]s no \f[CR]|\f[R]).-.PP-\f[B]\f[CB]payee:REGEX\f[B]\f[R]-.PD 0-.P-.PD-Match transaction payee/payer names (the part of the description left of-\f[CR]|\f[R], or the whole description if there\[aq]s no \f[CR]|\f[R]).-.PP-\f[B]\f[CB]real:, real:0\f[B]\f[R]-.PD 0-.P-.PD-Match real or virtual postings respectively.-.PP-\f[B]\f[CB]status:, status:!, status:*\f[B]\f[R]-.PD 0-.P-.PD-Match unmarked, pending, or cleared transactions respectively.-.PP-\f[B]\f[CB]type:TYPECODES\f[B]\f[R]-.PD 0-.P-.PD-Match by account type (see Declaring accounts > Account types).-\f[CR]TYPECODES\f[R] is one or more of the single\-letter account type-codes \f[CR]ALERXCV\f[R], case insensitive.-Note \f[CR]type:A\f[R] and \f[CR]type:E\f[R] will also match their-respective subtypes \f[CR]C\f[R] (Cash) and \f[CR]V\f[R] (Conversion).-Certain kinds of account alias can disrupt account types, see Rewriting-accounts > Aliases and account types.-.PP-\f[B]\f[CB]tag:REGEX[=REGEX]\f[B]\f[R]-.PD 0-.P-.PD-Match by tag name, and optionally also by tag value.-(To match only by value, use \f[CR]tag:.=REGEX\f[R].)-.PP-When querying by tag, note that:-.IP \[bu] 2-Accounts also inherit the tags of their parent accounts-.IP \[bu] 2-Postings also inherit the tags of their account and their transaction-.IP \[bu] 2-Transactions also acquire the tags of their postings.-.PP-(\f[B]\f[CB]inacct:ACCTNAME\f[B]\f[R]-.PD 0-.P-.PD-A special query term used automatically in hledger\-web only: tells-hledger\-web to show the transaction register for an account.)-.SS Combining query terms-When given multiple space\-separated query terms, most commands select-things which match:-.IP \[bu] 2-any of the description terms AND-.IP \[bu] 2-any of the account terms AND-.IP \[bu] 2-any of the status terms AND-.IP \[bu] 2-all the other terms.-.PP-The print command is a little different, showing transactions which:-.IP \[bu] 2-match any of the description terms AND-.IP \[bu] 2-have any postings matching any of the positive account terms AND-.IP \[bu] 2-have no postings matching any of the negative account terms AND-.IP \[bu] 2-match all the other terms.-.PP-We also support more complex boolean queries with the \f[CR]expr:\f[R]-prefix.-This allows one to combine query terms using \f[CR]and\f[R],-\f[CR]or\f[R], \f[CR]not\f[R] keywords (case insensitive), and to group-them by enclosing in parentheses.-.PP-Some examples:-.IP \[bu] 2-Exclude account names containing \[aq]food\[aq]:-.RS 2-.PP-\f[CR]expr:\[dq]not food\[dq]\f[R] (\f[CR]not:food\f[R] is equivalent)-.RE-.IP \[bu] 2-Match things which have \[aq]cool\[aq] in the description and the-\[aq]A\[aq] tag:-.RS 2-.PP-\f[CR]expr:\[dq]desc:cool and tag:A\[dq]\f[R]-(\f[CR]expr:\[dq]desc:cool tag:A\[dq]\f[R] is equivalent)-.RE-.IP \[bu] 2-Match things which either do not reference the \[aq]expenses:food\[aq]-account, or do have the \[aq]A\[aq] tag:-.RS 2-.PP-\f[CR]expr:\[dq]not expenses:food or tag:A\[dq]\f[R]-.RE-.IP \[bu] 2-Match things which either do not reference the \[aq]expenses:food\[aq]-account, or which reference the \[aq]expenses:drink\[aq] account and-also have the \[aq]A\[aq] tag:-.RS 2-.PP-\f[CR]expr:\[dq]expenses:food or (expenses:drink and tag:A)\[dq]\f[R]-.RE-.PP-\f[CR]expr:\f[R] has a restriction: \f[CR]date:\f[R] queries may not be-used inside \f[CR]or\f[R] expressions.-That would allow disjoint report periods or disjoint result sets, with-unclear semantics for our reports.-.SS Queries and command options-Some queries can also be expressed as command\-line options:-\f[CR]depth:2\f[R] is equivalent to \f[CR]\-\-depth 2\f[R],-\f[CR]date:2023\f[R] is equivalent to \f[CR]\-p 2023\f[R], etc.-When you mix command options and query arguments, generally the-resulting query is their intersection.-.SS Queries and account aliases-When account names are rewritten with \f[CR]\-\-alias\f[R] or-\f[CR]alias\f[R], \f[CR]acct:\f[R] will match either the old or the new-account name.-.SS Queries and valuation-When amounts are converted to other commodities in cost or value-reports, \f[CR]cur:\f[R] and \f[CR]amt:\f[R] match the old commodity-symbol and the old amount quantity, not the new ones.-(Except in hledger 1.22, #1625.)-.SH Pivoting-Normally, hledger groups and sums amounts within each account.-The \f[CR]\-\-pivot FIELD\f[R] option substitutes some other transaction-field for account names, causing amounts to be grouped and summed by-that field\[aq]s value instead.-FIELD can be any of the transaction fields \f[CR]acct\f[R],-\f[CR]status\f[R], \f[CR]code\f[R], \f[CR]desc\f[R], \f[CR]payee\f[R],-\f[CR]note\f[R], or a tag name.-When pivoting on a tag and a posting has multiple values of that tag,-only the first value is displayed.-Values containing \f[CR]colon:separated:parts\f[R] will be displayed-hierarchically, like account names.-Multiple, colon\-delimited fields can be pivoted simultaneously,-generating a hierarchical account name.-.PP-Some examples:-.IP-.EX-2016/02/16 Yearly Dues Payment-    assets:bank account                 2 EUR-    income:dues                        \-2 EUR  ; member: John Doe, kind: Lifetime-.EE-.PP-Normal balance report showing account names:-.IP-.EX-$ hledger balance-               2 EUR  assets:bank account-              \-2 EUR  income:dues-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--                   0-.EE-.PP-Pivoted balance report, using member: tag values instead:-.IP-.EX-$ hledger balance \-\-pivot member-               2 EUR-              \-2 EUR  John Doe-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--                   0-.EE-.PP-One way to show only amounts with a member: value (using a query):-.IP-.EX-$ hledger balance \-\-pivot member tag:member=.-              \-2 EUR  John Doe-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--              \-2 EUR-.EE-.PP-Another way (the acct: query matches against the pivoted \[dq]account-name\[dq]):-.IP-.EX-$ hledger balance \-\-pivot member acct:.-              \-2 EUR  John Doe-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--              \-2 EUR-.EE-.PP-Hierarchical reports can be generated with multiple pivots:-.IP-.EX-$ hledger balance Income:Dues \-\-pivot kind:member-              \-2 EUR  Lifetime:John Doe-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--              \-2 EUR-.EE-.SH Generating data-hledger has several features for generating data, such as:-.IP \[bu] 2-Periodic transaction rules can generate single or repeating transactions-following a template.-These are usually dated in the future, eg to help with forecasting.-They are activated by the \f[CR]\-\-forecast\f[R] option.-.IP \[bu] 2-The balance command\[aq]s \f[CR]\-\-budget\f[R] option uses these same-periodic rules to generate goals for the budget report.-.IP \[bu] 2-Auto posting rules can generate extra postings on certain matched-transactions.-They are always applied to forecast transactions; with the-\f[CR]\-\-auto\f[R] flag they are applied to transactions recorded in-the journal as well.-.IP \[bu] 2-The \f[CR]\-\-infer\-equity\f[R] flag infers missing conversion equity-postings from \[at]/\[at]\[at] costs.-And the inverse \f[CR]\-\-infer\-costs\f[R] flag infers missing-\[at]/\[at]\[at] costs from conversion equity postings.-.PP-Generated data of this kind is temporary, existing only at report time.-But you can see it in the output of \f[CR]hledger print\f[R], and you-can save that to your journal, in effect converting it from temporary-generated data to permanent recorded data.-This could be useful as a data entry aid.-.PP-If you are wondering what data is being generated and why, add the-\f[CR]\-\-verbose\-tags\f[R] flag.-In \f[CR]hledger print\f[R] output you will see extra tags like-\f[CR]generated\-transaction\f[R], \f[CR]generated\-posting\f[R], and-\f[CR]modified\f[R] on generated/modified data.-Also, even without \f[CR]\-\-verbose\-tags\f[R], generated data always-has equivalen hidden tags (with an underscore prefix), so eg you could-match generated transactions with-\f[CR]tag:_generated\-transaction\f[R].-.SH Forecasting-Forecasting, or speculative future reporting, can be useful for-estimating future balances, or for exploring different future scenarios.-.PP-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 \f[CR]future.journal\f[R] and include-that with \f[CR]\-f\f[R] only when you want to see them.-.SS \-\-forecast-There is another way: with the \f[CR]\-\-forecast\f[R] option, hledger-can generate temporary \[dq]forecast transactions\[dq] 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.-.PP-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.)-.PP-This is the \[dq]forecast period\[dq], 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-\f[CR]\-\-forecast=..2099\f[R] or-\f[CR]\-\-forecast=2023\-02\-15..\f[R].-Note that the \f[CR]=\f[R] is required.-.SS Inspecting forecast transactions-\f[CR]print\f[R] is the best command for inspecting and troubleshooting-forecast transactions.-Eg:-.IP-.EX-\[ti] monthly from 2022\-12\-20    rent-    assets:bank:checking-    expenses:rent           $1000-.EE-.IP-.EX-$ hledger print \-\-forecast \-\-today=2023/4/21-2023\-05\-20 rent-    ; generated\-transaction: \[ti] monthly from 2022\-12\-20-    assets:bank:checking-    expenses:rent                  $1000--2023\-06\-20 rent-    ; generated\-transaction: \[ti] monthly from 2022\-12\-20-    assets:bank:checking-    expenses:rent                  $1000--2023\-07\-20 rent-    ; generated\-transaction: \[ti] monthly from 2022\-12\-20-    assets:bank:checking-    expenses:rent                  $1000--2023\-08\-20 rent-    ; generated\-transaction: \[ti] monthly from 2022\-12\-20-    assets:bank:checking-    expenses:rent                  $1000--2023\-09\-20 rent-    ; generated\-transaction: \[ti] monthly from 2022\-12\-20-    assets:bank:checking-    expenses:rent                  $1000-.EE-.PP-Here there are no ordinary transactions, so the forecasted transactions-begin on the first occurence 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-Forecast transactions affect all reports, as you would expect.-Eg:-.IP-.EX-$ 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-.EE-.IP-.EX-$ 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 -.EE-.SS Forecast tags-Forecast transactions generated by \-\-forecast have a hidden tag,-\f[CR]_generated\-transaction\f[R].-So if you ever need to match forecast transactions, you could use-\f[CR]tag:_generated\-transaction\f[R] (or just-\f[CR]tag:generated\f[R]) in a query.-.PP-For troubleshooting, you can add the \f[CR]\-\-verbose\-tags\f[R] flag.-Then, visible \f[CR]generated\-transaction\f[R] tags will be added also,-so you can view them with the \f[CR]print\f[R] command.-Their value indicates which periodic rule was responsible.-.SS 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:-.PP-The forecast period starts on:-.IP \[bu] 2-the later of-.RS 2-.IP \[bu] 2-the start date in the periodic transaction rule-.IP \[bu] 2-the start date in \f[CR]\-\-forecast\f[R]\[aq]s argument-.RE-.IP \[bu] 2-otherwise (if those are not available): the later of-.RS 2-.IP \[bu] 2-the report start date specified with-\f[CR]\-b\f[R]/\f[CR]\-p\f[R]/\f[CR]date:\f[R]-.IP \[bu] 2-the day after the latest ordinary transaction in the journal-.RE-.IP \[bu] 2-otherwise (if none of these are available): today.-.PP-The forecast period ends on:-.IP \[bu] 2-the earlier of-.RS 2-.IP \[bu] 2-the end date in the periodic transaction rule-.IP \[bu] 2-the end date in \f[CR]\-\-forecast\f[R]\[aq]s argument-.RE-.IP \[bu] 2-otherwise: the report end date specified with-\f[CR]\-e\f[R]/\f[CR]\-p\f[R]/\f[CR]date:\f[R]-.IP \[bu] 2-otherwise: 180 days (\[ti]6 months) from today.-.SS Forecast troubleshooting-When \-\-forecast is not doing what you expect, one of these tips should-help:-.IP \[bu] 2-Remember to use the \f[CR]\-\-forecast\f[R] option.-.IP \[bu] 2-Remember to have at least one periodic transaction rule in your journal.-.IP \[bu] 2-Test with \f[CR]print \-\-forecast\f[R].-.IP \[bu] 2-Check for typos or too\-restrictive start/end dates in your periodic-transaction rule.-.IP \[bu] 2-Leave at least 2 spaces between the rule\[aq]s period expression and-description fields.-.IP \[bu] 2-Check for future\-dated ordinary transactions suppressing forecasted-transactions.-.IP \[bu] 2-Try setting explicit report start and/or end dates with \f[CR]\-b\f[R],-\f[CR]\-e\f[R], \f[CR]\-p\f[R] or \f[CR]date:\f[R]-.IP \[bu] 2-Try adding the \f[CR]\-E\f[R] flag to encourage display of empty-periods/zero transactions.-.IP \[bu] 2-Try setting explicit forecast start and/or end dates with-\f[CR]\-\-forecast=START..END\f[R]-.IP \[bu] 2-Consult Forecast period, in detail, above.-.IP \[bu] 2-Check inside the engine: add \f[CR]\-\-debug=2\f[R] (eg).-.SH Budgeting-With the balance command\[aq]s \f[CR]\-\-budget\f[R] report, each-periodic transaction rule generates recurring budget goals in specified-accounts, and goals and actual performance can be compared.-See the balance command\[aq]s doc below.-.PP-You can generate budget goals and forecast transactions at the same-time, from the same or different periodic transaction rules:-\f[CR]hledger bal \-M \-\-budget \-\-forecast ...\f[R]-.PP-See also: Budgeting and Forecasting.-.SH 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 \[dq]cost\[dq], for convenience; feel free-to mentally translate to \[dq]conversion rate\[dq] or \[dq]selling-price\[dq] if helpful.-.SS Recording costs-We\[aq]ll explore several ways of recording transactions involving-costs.-These are also summarised at hledger Cookbook > Cost notation.-.PP-Costs can be recorded explicitly in the journal, using the-\f[CR]\[at] UNITCOST\f[R] or \f[CR]\[at]\[at] TOTALCOST\f[R] notation-described in Journal > Costs:-.PP-\f[B]Variant 1\f[R]-.IP-.EX-2022\-01\-01-  assets:dollars    $\-135-  assets:euros       €100 \[at] $1.35   ; $1.35 per euro (unit cost)-.EE-.PP-\f[B]Variant 2\f[R]-.IP-.EX-2022\-01\-01-  assets:dollars    $\-135-  assets:euros       €100 \[at]\[at] $135   ; $135 total cost-.EE-.PP-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.-.PP-Costs can also be left implicit, and hledger will infer the cost that is-consistent with a balanced transaction:-.PP-\f[B]Variant 3\f[R]-.IP-.EX-2022\-01\-01-  assets:dollars    $\-135-  assets:euros       €100-.EE-.PP-Here, hledger will attach a \f[CR]\[at]\[at] €100\f[R] cost to the first-amount (you can see it with \f[CR]hledger print \-x\f[R]).-This form looks convenient, but there are downsides:-.IP \[bu] 2-It sacrifices some error checking.-For example, if you accidentally wrote €10 instead of €100, hledger-would not be able to detect the mistake.-.IP \[bu] 2-It is sensitive to the order of postings \- if they were reversed, a-different entry would be inferred and reports would be different.-.IP \[bu] 2-The per\-unit cost basis is not easy to read.-.PP-So generally this kind of entry is not recommended.-You can make sure you have none of these by using \f[CR]\-s\f[R] (strict-mode), or by running \f[CR]hledger check balanced\f[R].-.SS Reporting at cost-Now when you add the \f[CR]\-B\f[R]/\f[CR]\-\-cost\f[R] flag to reports-(\[dq]B\[dq] is from Ledger\[aq]s \-B/\-\-basis/\-\-cost flag), any-amounts which have been annotated with costs will be converted to their-cost\[aq]s commodity (in the report output).-Ie they will be displayed \[dq]at cost\[dq] or \[dq]at sale price\[dq].-.PP-Some things to note:-.IP \[bu] 2-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.-.IP \[bu] 2-Conversion to cost is performed before conversion to market value-(described below).-.SS Equity conversion postings-There is a problem with the entries above \- they are not conventional-Double Entry Bookkeeping (DEB) notation, and because of the-\[dq]magical\[dq] 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-\f[CR]hledger bse\f[R].-.PP-For most hledger users, this doesn\[aq]t matter in practice and can-safely be ignored !-But if you\[aq]d like to learn more, keep reading.-.PP-Conventional DEB uses an extra pair of equity postings to balance the-transaction.-Of course you can do this in hledger as well:-.PP-\f[B]Variant 4\f[R]-.IP-.EX-2022\-01\-01-    assets:dollars      $\-135-    assets:euros         €100-    equity:conversion    $135-    equity:conversion   €\-100-.EE-.PP-Now the transaction is perfectly balanced according to standard DEB, and-\f[CR]hledger bse\f[R]\[aq]s total will not be disrupted.-.PP-And, hledger can still infer the cost for cost reporting, but it\[aq]s-not done by default \- you must add the \f[CR]\-\-infer\-costs\f[R] flag-like so:-.IP-.EX-$ hledger print \-\-infer\-costs-2022\-01\-01 one hundred euros purchased at $1.35 each-    assets:dollars       $\-135 \[at]\[at] €100-    assets:euros                  €100-    equity:conversion             $135-    equity:conversion            €\-100-.EE-.IP-.EX-$ hledger bal \-\-infer\-costs \-B-               €\-100  assets:dollars                                                                                                                                              -                €100  assets:euros                                                                                                                                                -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-                                                                                                                                                              -                   0                                                                                                                                                              -.EE-.PP-Here are some downsides of this kind of entry:-.IP \[bu] 2-The per\-unit cost basis is not easy to read.-.IP \[bu] 2-Instead of \f[CR]\-B\f[R] you must remember to type-\f[CR]\-B \-\-infer\-costs\f[R].-.IP \[bu] 2-\f[CR]\-\-infer\-costs\f[R] 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.-.SS Inferring equity conversion postings-Can we go in the other direction ?-Yes, if you have transactions written with the \[at]/\[at]\[at] cost-notation, hledger can infer the missing equity postings, if you add the-\f[CR]\-\-infer\-equity\f[R] flag.-Eg:-.IP-.EX-2022\-01\-01-  assets:dollars  \-$135-  assets:euros     €100 \[at] $1.35-.EE-.IP-.EX-$ hledger print \-\-infer\-equity-2022\-01\-01-    assets:dollars                    $\-135-    assets:euros               €100 \[at] $1.35-    equity:conversion:$\-€:€           €\-100-    equity:conversion:$\-€:$         $135.00-.EE-.PP-The equity account names will be \[dq]equity:conversion:A\-B:A\[dq] and-\[dq]equity:conversion:A\-B:B\[dq] where A is the alphabetically first-commodity symbol.-You can customise the \[dq]equity:conversion\[dq] part by declaring an-account with the \f[CR]V\f[R]/\f[CR]Conversion\f[R] account type.-.SS Combining costs and equity conversion postings-Finally, you can use both the \[at]/\[at]\[at] 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:-.PP-\f[B]Variant 5\f[R]-.IP-.EX-2022\-01\-01 one hundred euros purchased at $1.35 each-    assets:dollars      $\-135-    equity:conversion    $135-    equity:conversion   €\-100-    assets:euros         €100 \[at] $1.35-.EE-.PP-All the other variants above can (usually) be rewritten to this final-form with:-.IP-.EX-$ hledger print \-x \-\-infer\-costs \-\-infer\-equity-.EE-.PP-Downsides:-.IP \[bu] 2-The precise format of the journal entry becomes more important.-If hledger can\[aq]t detect and match up the cost and equity postings,-it will give a transaction balancing error.-.IP \[bu] 2-The add command does not yet accept this kind of entry (#2056).-.IP \[bu] 2-This is the most verbose form.-.SS Requirements for detecting equity conversion postings-\f[CR]\-\-infer\-costs\f[R] has certain requirements (unlike-\f[CR]\-\-infer\-equity\f[R], which always works).-It will infer costs only in transactions with:-.IP \[bu] 2-Two non\-equity postings, in different commodities.-Their order is significant: the cost will be added to the first of them.-.IP \[bu] 2-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\[aq]s amount.-Equity conversion accounts are:-.RS 2-.IP \[bu] 2-any accounts declared with account type-\f[CR]V\f[R]/\f[CR]Conversion\f[R], or their subaccounts-.IP \[bu] 2-otherwise, accounts named \f[CR]equity:conversion\f[R],-\f[CR]equity:trade\f[R], or \f[CR]equity:trading\f[R], or their-subaccounts.-.RE-.PP-And multiple such four\-posting groups can coexist within a single-transaction.-When \f[CR]\-\-infer\-costs\f[R] fails, it does not infer a cost in that-transaction, and does not raise an error (ie, it infers costs where it-can).-.PP-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 \[dq]unbalanced-transaction\[dq] error.-.SS Infer cost and equity by default ?-Should \f[CR]\-\-infer\-costs\f[R] and \f[CR]\-\-infer\-equity\f[R] be-enabled by default ?-Try using them always, eg with a shell alias:-.IP-.EX-alias h=\[dq]hledger \-\-infer\-equity \-\-infer\-costs\[dq]-.EE-.PP-and let us know what problems you find.-.PP-.SH Value reporting-Instead of reporting amounts in their original commodity, hledger can-convert them to cost/sale amount (using the conversion rate recorded in-the transaction), and/or to market value (using some market price on a-certain date).-This is controlled by the \f[CR]\-\-value=TYPE[,COMMODITY]\f[R] option,-which will be described below.-We also provide the simpler \f[CR]\-V\f[R] and \f[CR]\-X COMMODITY\f[R]-options, and often one of these is all you need:-.SS \-V: Value-The \f[CR]\-V/\-\-market\f[R] flag converts amounts to market value in-their default \f[I]valuation commodity\f[R], using the market prices in-effect on the \f[I]valuation date(s)\f[R], if any.-More on these in a minute.-.SS \-X: Value in specified commodity-The \f[CR]\-X/\-\-exchange=COMM\f[R] option is like \f[CR]\-V\f[R],-except you tell it which currency you want to convert to, and it tries-to convert everything to that.-.SS 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 \[dq]end\[dq] dates for valuation.-More specifically:-.IP \[bu] 2-For single period reports (including normal print and register reports):-.RS 2-.IP \[bu] 2-If an explicit report end date is specified, that is used-.IP \[bu] 2-Otherwise the latest transaction date or P directive date is used (even-if it\[aq]s in the future)-.RE-.IP \[bu] 2-For multiperiod reports, each period is valued on its last day.-.PP-This can be customised with the \-\-value option described below, which-can select either \[dq]then\[dq], \[dq]end\[dq], \[dq]now\[dq], or-\[dq]custom\[dq] dates.-(Note, this has a bug in hledger\-ui <=1.31: turning on valuation with-the \f[CR]V\f[R] key always resets it to \[dq]end\[dq].)-.SS 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:-.IP "1." 3-A \f[I]declared market price\f[R] or \f[I]inferred market price\f[R]:-A\[aq]s latest market price in B on or before the valuation date as-declared by a P directive, or (with the-\f[CR]\-\-infer\-market\-prices\f[R] flag) inferred from costs.-\-.IP "2." 3-A \f[I]reverse market price\f[R]: the inverse of a declared or inferred-market price from B to A.-.IP "3." 3-A \f[I]forward chain of market prices\f[R]: a synthetic price formed by-combining the shortest chain of \[dq]forward\[dq] (only 1 above) market-prices, leading from A to B.-.IP "4." 3-\f[I]Any chain of market prices\f[R]: a chain of any market prices,-including both forward and reverse prices (1 and 2 above), leading from-A to B.-.PP-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 \[dq]gave up\[dq] message visible-in \f[CR]\-\-debug=2\f[R] output).-That limit is currently 1000.-.PP-Amounts for which no suitable market price can be found, are not-converted.-.SS \-\-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 \f[CR]\-\-infer\-market\-prices\f[R] flag to \f[CR]\-V\f[R],-\f[CR]\-X\f[R] or \f[CR]\-\-value\f[R] enables this.-.PP-So for example, \f[CR]hledger bs \-V \-\-infer\-market\-prices\f[R] will-get market prices both from P directives and from transactions.-If both occur on the same day, the P directive takes precedence.-.PP-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 \f[CR]\-\-debug\f[R] or \f[CR]\-\-debug=2\f[R]-to troubleshoot.-.PP-\f[CR]\-\-infer\-market\-prices\f[R] can infer market prices from:-.IP \[bu] 2-multicommodity transactions with explicit prices-(\f[CR]\[at]\f[R]/\f[CR]\[at]\[at]\f[R])-.IP \[bu] 2-multicommodity transactions with implicit prices (no \f[CR]\[at]\f[R],-two commodities, unbalanced).-(With these, the order of postings matters.-\f[CR]hledger print \-x\f[R] can be useful for troubleshooting.)-.IP \[bu] 2-multicommodity transactions with equity postings, if cost is inferred-with \f[CR]\-\-infer\-costs\f[R].-.PP-There is a limitation (bug) currently: when a valuation commodity is not-specified, prices inferred with \f[CR]\-\-infer\-market\-prices\f[R] do-not help select a default valuation commodity, as \f[CR]P\f[R] prices-would.-So conversion might not happen because no valuation commodity was-detected (\f[CR]\-\-debug=2\f[R] will show this).-To be safe, specify the valuation commmodity, eg:-.IP \[bu] 2-\f[CR]\-X EUR \-\-infer\-market\-prices\f[R], not-\f[CR]\-V \-\-infer\-market\-prices\f[R]-.IP \[bu] 2-\f[CR]\-\-value=then,EUR \-\-infer\-market\-prices\f[R], not-\f[CR]\-\-value=then \-\-infer\-market\-prices\f[R]-.PP-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.)-.IP-.EX-2022\-01\-01 Positive Unit prices-    a        A 1-    b        B \-1 \[at] A 1--2022\-01\-01 Positive Total prices-    a        A 1-    b        B \-1 \[at]\[at] A 1---2022\-01\-02 Negative unit prices-    a        A 1-    b        B 1 \[at] A \-1--2022\-01\-02 Negative total prices-    a        A 1-    b        B 1 \[at]\[at] A \-1---2022\-01\-03 Double Negative unit prices-    a        A \-1-    b        B \-1 \[at] A \-1--2022\-01\-03 Double Negative total prices-    a        A \-1-    b        B \-1 \[at]\[at] A \-1-.EE-.PP-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:-.IP-.EX-$ 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-.EE-.SS Valuation commodity-\f[B]When you specify a valuation commodity (\f[CB]\-X COMM\f[B] or-\f[CB]\-\-value TYPE,COMM\f[B]):\f[R]-.PD 0-.P-.PD-hledger will convert all amounts to COMM, wherever it can find a-suitable market price (including by reversing or chaining prices).-.PP-\f[B]When you leave the valuation commodity unspecified (\f[CB]\-V\f[B]-or \f[CB]\-\-value TYPE\f[B]):\f[R]-.PD 0-.P-.PD-For each commodity A, hledger picks a default valuation commodity as-follows, in this order of preference:-.IP "1." 3-The price commodity from the latest P\-declared market price for A on or-before valuation date.-.IP "2." 3-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.)-.IP "3." 3-If there are no P directives at all (any commodity or date) and the-\f[CR]\-\-infer\-market\-prices\f[R] flag is used: the price commodity-from the latest transaction\-inferred price for A on or before valuation-date.-.PP-This means:-.IP \[bu] 2-If you have P directives, they determine which commodities-\f[CR]\-V\f[R] will convert, and to what.-.IP \[bu] 2-If you have no P directives, and use the-\f[CR]\-\-infer\-market\-prices\f[R] flag, costs determine it.-.PP-Amounts for which no valuation commodity can be found are not converted.-.SS \-\-value: Flexible valuation-\f[CR]\-V\f[R] and \f[CR]\-X\f[R] are special cases of the more general-\f[CR]\-\-value\f[R] option:-.IP-.EX- \-\-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-.EE-.PP-The TYPE part selects cost or value and valuation date:-.TP-\f[CR]\-\-value=then\f[R]-Convert amounts to their value in the default valuation commodity, using-market prices on each posting\[aq]s date.-.TP-\f[CR]\-\-value=end\f[R]-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\[aq]s end date); or in multiperiod reports, market prices on-the last day of each subperiod.-.TP-\f[CR]\-\-value=now\f[R]-Convert amounts to their value in the default valuation commodity using-current market prices (as of when report is generated).-.TP-\f[CR]\-\-value=YYYY\-MM\-DD\f[R]-Convert amounts to their value in the default valuation commodity using-market prices on this date.-.PP-To select a different valuation commodity, add the optional-\f[CR],COMM\f[R] part: a comma, then the target commodity\[aq]s symbol.-Eg: \f[B]\f[CB]\-\-value=now,EUR\f[B]\f[R].-hledger will do its best to convert amounts to this commodity, deducing-market prices as described above.-.SS Valuation examples-Here are some quick examples of \f[CR]\-V\f[R]:-.IP-.EX-; 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-.EE-.PP-How many euros do I have ?-.IP-.EX-$ hledger \-f t.j bal \-N euros-                €100  assets:euros-.EE-.PP-What are they worth at end of nov 3 ?-.IP-.EX-$ hledger \-f t.j bal \-N euros \-V \-e 2016/11/4-             $110.00  assets:euros-.EE-.PP-What are they worth after 2016/12/21 ?-(no report end date specified, defaults to today)-.IP-.EX-$ hledger \-f t.j bal \-N euros \-V-             $103.00  assets:euros-.EE-.PP-Here are some examples showing the effect of \f[CR]\-\-value\f[R], as-seen with \f[CR]print\f[R]:-.IP-.EX-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 \[at] 5 B--2000\-02\-01-  (a)      1 A \[at] 6 B--2000\-03\-01-  (a)      1 A \[at] 7 B-.EE-.PP-Show the cost of each posting:-.IP-.EX-$ hledger \-f\- print \-\-cost-2000\-01\-01-    (a)             5 B--2000\-02\-01-    (a)             6 B--2000\-03\-01-    (a)             7 B-.EE-.PP-Show the value as of the last day of the report period (2000\-02\-29):-.IP-.EX-$ hledger \-f\- print \-\-value=end date:2000/01\-2000/03-2000\-01\-01-    (a)             2 B--2000\-02\-01-    (a)             2 B-.EE-.PP-With no report period specified, that shows the value as of the last day-of the journal (2000\-03\-01):-.IP-.EX-$ hledger \-f\- print \-\-value=end-2000\-01\-01-    (a)             3 B--2000\-02\-01-    (a)             3 B--2000\-03\-01-    (a)             3 B-.EE-.PP-Show the current value (the 2000\-04\-01 price is still in effect-today):-.IP-.EX-$ hledger \-f\- print \-\-value=now-2000\-01\-01-    (a)             4 B--2000\-02\-01-    (a)             4 B--2000\-03\-01-    (a)             4 B-.EE-.PP-Show the value on 2000/01/15:-.IP-.EX-$ 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-.EE-.SS Interaction of valuation and queries-When matching postings based on queries in the presence of valuation,-the following happens:-.IP "1." 3-The query is separated into two parts:-.RS 4-.IP "1." 3-the currency (\f[CR]cur:\f[R]) or amount (\f[CR]amt:\f[R]).-.IP "2." 3-all other parts.-.RE-.IP "2." 3-The postings are matched to the currency and amount queries based on-pre\-valued amounts.-.IP "3." 3-Valuation is applied to the postings.-.IP "4." 3-The postings are matched to the other parts of the query based on-post\-valued amounts.-.PP-Related: #1625-.SS Effect of valuation on reports-Here is a reference for how valuation is supposed to affect each part of-hledger\[aq]s reports.-(It\[aq]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.-.PP-First, a quick glossary:-.TP-\f[I]cost\f[R]-calculated using price(s) recorded in the transaction(s).-.TP-\f[I]value\f[R]-market value using available market price declarations, or the unchanged-amount if no conversion rate can be found.-.TP-\f[I]report start\f[R]-the first day of the report period specified with \-b or \-p or date:,-otherwise today.-.TP-\f[I]report or journal start\f[R]-the first day of the report period specified with \-b or \-p or date:,-otherwise the earliest transaction date in the journal, otherwise today.-.TP-\f[I]report end\f[R]-the last day of the report period specified with \-e or \-p or date:,-otherwise today.-.TP-\f[I]report or journal end\f[R]-the last day of the report period specified with \-e or \-p or date:,-otherwise the latest transaction date in the journal, otherwise today.-.TP-\f[I]report interval\f[R]-a flag (\-D/\-W/\-M/\-Q/\-Y) or period expression that activates the-report\[aq]s multi\-period mode (whether showing one or many-subperiods).-.PP-.TS-tab(@);-lw(9.5n) lw(11.8n) lw(12.0n) lw(17.2n) lw(12.0n) lw(7.4n).-T{-Report type-T}@T{-\f[CR]\-B\f[R], \f[CR]\-\-cost\f[R]-T}@T{-\f[CR]\-V\f[R], \f[CR]\-X\f[R]-T}@T{-\f[CR]\-\-value=then\f[R]-T}@T{-\f[CR]\-\-value=end\f[R]-T}@T{-\f[CR]\-\-value=DATE\f[R], \f[CR]\-\-value=now\f[R]-T}-_-T{-\f[B]print\f[R]-T}@T{-T}@T{-T}@T{-T}@T{-T}@T{-T}-T{-posting amounts-T}@T{-cost-T}@T{-value at report end or today-T}@T{-value at posting date-T}@T{-value at report or journal end-T}@T{-value at DATE/today-T}-T{-balance assertions/assignments-T}@T{-unchanged-T}@T{-unchanged-T}@T{-unchanged-T}@T{-unchanged-T}@T{-unchanged-T}-T{-T}@T{-T}@T{-T}@T{-T}@T{-T}@T{-T}-T{-\f[B]register\f[R]-T}@T{-T}@T{-T}@T{-T}@T{-T}@T{-T}-T{-starting balance (\-H)-T}@T{-cost-T}@T{-value at report or journal end-T}@T{-valued at day each historical posting was made-T}@T{-value at report or journal end-T}@T{-value at DATE/today-T}-T{-starting balance (\-H) with report interval-T}@T{-cost-T}@T{-value at day before report or journal start-T}@T{-valued at day each historical posting was made-T}@T{-value at day before report or journal start-T}@T{-value at DATE/today-T}-T{-posting amounts-T}@T{-cost-T}@T{-value at report or journal end-T}@T{-value at posting date-T}@T{-value at report or journal end-T}@T{-value at DATE/today-T}-T{-summary posting amounts with report interval-T}@T{-summarised cost-T}@T{-value at period ends-T}@T{-sum of postings in interval, valued at interval start-T}@T{-value at period ends-T}@T{-value at DATE/today-T}-T{-running total/average-T}@T{-sum/average of displayed values-T}@T{-sum/average of displayed values-T}@T{-sum/average of displayed values-T}@T{-sum/average of displayed values-T}@T{-sum/average of displayed values-T}-T{-T}@T{-T}@T{-T}@T{-T}@T{-T}@T{-T}-T{-\f[B]balance (bs, bse, cf, is)\f[R]-T}@T{-T}@T{-T}@T{-T}@T{-T}@T{-T}-T{-balance changes-T}@T{-sums of costs-T}@T{-value at report end or today of sums of postings-T}@T{-value at posting date-T}@T{-value at report or journal end of sums of postings-T}@T{-value at DATE/today of sums of postings-T}-T{-budget amounts (\-\-budget)-T}@T{-like balance changes-T}@T{-like balance changes-T}@T{-like balance changes-T}@T{-like balances-T}@T{-like balance changes-T}-T{-grand total-T}@T{-sum of displayed values-T}@T{-sum of displayed values-T}@T{-sum of displayed valued-T}@T{-sum of displayed values-T}@T{-sum of displayed values-T}-T{-T}@T{-T}@T{-T}@T{-T}@T{-T}@T{-T}-T{-\f[B]balance (bs, bse, cf, is) with report interval\f[R]-T}@T{-T}@T{-T}@T{-T}@T{-T}@T{-T}-T{-starting balances (\-H)-T}@T{-sums of costs of postings before report start-T}@T{-value at report start of sums of all postings before report start-T}@T{-sums of values of postings before report start at respective posting-dates-T}@T{-value at report start of sums of all postings before report start-T}@T{-sums of postings before report start-T}-T{-balance changes (bal, is, bs \-\-change, cf \-\-change)-T}@T{-sums of costs of postings in period-T}@T{-same as \-\-value=end-T}@T{-sums of values of postings in period at respective posting dates-T}@T{-balance change in each period, valued at period ends-T}@T{-value at DATE/today of sums of postings-T}-T{-end balances (bal \-H, is \-\-H, bs, cf)-T}@T{-sums of costs of postings from before report start to period end-T}@T{-same as \-\-value=end-T}@T{-sums of values of postings from before period start to period end at-respective posting dates-T}@T{-period end balances, valued at period ends-T}@T{-value at DATE/today of sums of postings-T}-T{-budget amounts (\-\-budget)-T}@T{-like balance changes/end balances-T}@T{-like balance changes/end balances-T}@T{-like balance changes/end balances-T}@T{-like balances-T}@T{-like balance changes/end balances-T}-T{-row totals, row averages (\-T, \-A)-T}@T{-sums, averages of displayed values-T}@T{-sums, averages of displayed values-T}@T{-sums, averages of displayed values-T}@T{-sums, averages of displayed values-T}@T{-sums, averages of displayed values-T}-T{-column totals-T}@T{-sums of displayed values-T}@T{-sums of displayed values-T}@T{-sums of displayed values-T}@T{-sums of displayed values-T}@T{-sums of displayed values-T}-T{-grand total, grand average-T}@T{-sum, average of column totals-T}@T{-sum, average of column totals-T}@T{-sum, average of column totals-T}@T{-sum, average of column totals-T}@T{-sum, average of column totals-T}-T{-T}@T{-T}@T{-T}@T{-T}@T{-T}@T{-T}-.TE-.PP-\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-.SS Commands overview-Here are the built\-in commands:-.SS DATA ENTRY-These data entry commands are the only ones which can modify your-journal file.-.IP \[bu] 2-add \- add transactions using terminal prompts-.IP \[bu] 2-import \- add new transactions from other files, eg CSV files-.SS DATA CREATION-.IP \[bu] 2-close \- generate balance\-zeroing/restoring transactions-.IP \[bu] 2-rewrite \- generate auto postings, like print \-\-auto-.SS DATA MANAGEMENT-.IP \[bu] 2-check \- check for various kinds of error in the data-.IP \[bu] 2-diff \- compare account transactions in two journal files-.SS REPORTS, FINANCIAL-.IP \[bu] 2-aregister (areg) \- show transactions in a particular account-.IP \[bu] 2-balancesheet (bs) \- show assets, liabilities and net worth-.IP \[bu] 2-balancesheetequity (bse) \- show assets, liabilities and equity-.IP \[bu] 2-cashflow (cf) \- show changes in liquid assets-.IP \[bu] 2-incomestatement (is) \- show revenues and expenses-.SS REPORTS, VERSATILE-.IP \[bu] 2-balance (bal) \- show balance changes, end balances, budgets, gains..-.IP \[bu] 2-print \- show transactions or export journal data-.IP \[bu] 2-register (reg) \- show postings in one or more accounts & running total-.IP \[bu] 2-roi \- show return on investments-.SS REPORTS, BASIC-.IP \[bu] 2-accounts \- show account names-.IP \[bu] 2-activity \- show bar charts of posting counts per period-.IP \[bu] 2-codes \- show transaction codes-.IP \[bu] 2-commodities \- show commodity/currency symbols-.IP \[bu] 2-descriptions \- show transaction descriptions-.IP \[bu] 2-files \- show input file paths-.IP \[bu] 2-notes \- show note parts of transaction descriptions-.IP \[bu] 2-payees \- show payee parts of transaction descriptions-.IP \[bu] 2-prices \- show market prices-.IP \[bu] 2-stats \- show journal statistics-.IP \[bu] 2-tags \- show tag names-.IP \[bu] 2-test \- run self tests-.SS HELP-.IP \[bu] 2-help \- show the hledger manual with info/man/pager-.IP \[bu] 2-demo \- show small hledger demos in the terminal-.PP-\-.SS ADD\-ONS-And here are some typical add\-on commands.-Some of these are installed by the hledger\-install script.-If installed, they will appear in hledger\[aq]s commands list:-.IP \[bu] 2-ui \- run hledger\[aq]s terminal UI-.IP \[bu] 2-web \- run hledger\[aq]s web UI-.IP \[bu] 2-iadd \- add transactions using a TUI (currently hard to build)-.IP \[bu] 2-interest \- generate interest transactions-.IP \[bu] 2-stockquotes \- download market prices from AlphaVantage-.IP \[bu] 2-Scripts and add\-ons \- check\-fancyassertions, edit, fifo, git, move,-pijul, plot, and more..-.PP-Next, each command is described in detail, in alphabetical order.-.SS accounts-Show account names.-.PP-This command lists account names.-By default it shows all known accounts, either used in transactions or-declared with account directives.-.PP-With query arguments, only matched account names and account names-referenced by matched postings are shown.-.PP-Or it can show just the used accounts-(\f[CR]\-\-used\f[R]/\f[CR]\-u\f[R]), the declared accounts-(\f[CR]\-\-declared\f[R]/\f[CR]\-d\f[R]), the accounts declared but not-used (\f[CR]\-\-unused\f[R]), the accounts used but not declared-(\f[CR]\-\-undeclared\f[R]), or the first account matched by an account-name pattern, if any (\f[CR]\-\-find\f[R]).-.PP-It shows a flat list by default.-With \f[CR]\-\-tree\f[R], it uses indentation to show the account-hierarchy.-In flat mode you can add \f[CR]\-\-drop N\f[R] to omit the first few-account name components.-Account names can be depth\-clipped with \f[CR]depth:N\f[R] or-\f[CR]\-\-depth N\f[R] or \f[CR]\-N\f[R].-.PP-With \f[CR]\-\-types\f[R], it also shows each account\[aq]s type, if-it\[aq]s known.-(See Declaring accounts > Account types.)-.PP-With \f[CR]\-\-positions\f[R], it also shows the file and line number of-each account\[aq]s declaration, if any, and the account\[aq]s overall-declaration order; these may be useful when troubleshooting account-display order.-.PP-With \f[CR]\-\-directives\f[R], it adds the \f[CR]account\f[R] keyword,-showing valid account directives which can be pasted into a journal-file.-This is useful together with \f[CR]\-\-undeclared\f[R] when updating-your account declarations to satisfy \f[CR]hledger check accounts\f[R].-.PP-The \f[CR]\-\-find\f[R] flag can be used to look up a single account-name, in the same way that the \f[CR]aregister\f[R] command does.-It returns the alphanumerically\-first matched account name, or if none-can be found, it fails with a non\-zero exit code.-.PP-Examples:-.IP-.EX-$ hledger accounts-assets:bank:checking-assets:bank:saving-assets:cash-expenses:food-expenses:supplies-income:gifts-income:salary-liabilities:debts-.EE-.IP-.EX-$ hledger accounts \-\-undeclared \-\-directives >> $LEDGER_FILE-$ hledger check accounts-.EE-.SS activity-Show an ascii barchart of posting counts per interval.-.PP-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.-.PP-Examples:-.IP-.EX-$ hledger activity \-\-quarterly-2008\-01\-01 **-2008\-04\-01 *******-2008\-07\-01 -2008\-10\-01 **-.EE-.SS add-Prompt for transactions and add them to the journal.-Any arguments will be used as default inputs for the first N prompts.-.PP-Many hledger users edit their journals directly with a text editor, or-generate them from CSV.-For more interactive data entry, there is the \f[CR]add\f[R] 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 \f[CR]import\f[R]).-.PP-To use it, just run \f[CR]hledger add\f[R] and follow the prompts.-You can add as many transactions as you like; when you are finished,-enter \f[CR].\f[R] or press control\-d or control\-c to exit.-.PP-Features:-.IP \[bu] 2-add tries to provide useful defaults, using the most similar (by-description) recent transaction (filtered by the query, if any) as a-template.-.IP \[bu] 2-You can also set the initial defaults with command line arguments.-.IP \[bu] 2-Readline\-style edit keys can be used during data entry.-.IP \[bu] 2-The tab key will auto\-complete whenever possible \- accounts,-payees/descriptions, dates (\f[CR]yesterday\f[R], \f[CR]today\f[R],-\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.-.IP \[bu] 2-If you make a mistake, enter \f[CR]<\f[R] at any prompt to go one step-backward.-.IP \[bu] 2-Input prompts are displayed in a different colour when the terminal-supports it.-.PP-Example (see https://hledger.org/add.html for a detailed tutorial):-.IP-.EX-$ hledger add-Adding transactions to journal file /src/hledger/examples/sample.journal-Any command line arguments will be used as defaults.-Use tab key to complete, readline keys to edit, enter to accept defaults.-An optional (CODE) may follow transaction dates.-An optional ; COMMENT may follow descriptions or amounts.-If you make a mistake, enter < at any prompt to go one step backward.-To end a transaction, enter . when prompted.-To quit, enter . at a date prompt or press control\-d or control\-c.-Date [2015/05/22]: -Description: supermarket-Account 1: expenses:food-Amount  1: $10-Account 2: assets:checking-Amount  2 [$\-10.0]: -Account 3 (or . or enter to finish this transaction): .-2015/05/22 supermarket-    expenses:food             $10-    assets:checking        $\-10.0--Save this transaction to the journal ? [y]: -Saved.-Starting the next transaction (. or ctrl\-D/ctrl\-C to quit)-Date [2015/05/22]: <CTRL\-D> $-.EE-.PP-If you enter a number with no commodity symbol, and you have declared a-default commodity with a \f[CR]D\f[R] directive, you might expect-\f[CR]add\f[R] to add this symbol for you.-It does not do this; we assume that if you are using a \f[CR]D\f[R]-directive you prefer not to see the commodity symbol repeated on amounts-in the journal.-.SS aregister-(areg)-.PP-Show the transactions and running historical balance of a single-account, with each transaction displayed as one line.-.PP-\f[CR]aregister\f[R] 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 (\f[CR]\-\-historical\f[R] mode is always on).-.PP-This is a more \[dq]real world\[dq], bank\-like view than the-\f[CR]register\f[R] command (which shows individual postings, possibly-from multiple accounts, not necessarily in historical mode).-As a quick rule of thumb: \- use \f[CR]aregister\f[R] for reviewing and-reconciling real\-world asset/liability accounts \- use-\f[CR]register\f[R] for reviewing detailed revenues/expenses.-.PP-\f[CR]aregister\f[R] 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.-.PP-When there are multiple matches, the alphabetically\-first choice can be-surprising; eg if you have \f[CR]assets:per:checking 1\f[R] and-\f[CR]assets:biz:checking 2\f[R] accounts,-\f[CR]hledger areg checking\f[R] would select-\f[CR]assets:biz:checking 2\f[R].-It\[aq]s just a convenience to save typing, so if in doubt, write the-full account name, or a distinctive substring that matches uniquely.-.PP-Transactions involving subaccounts of this account will also be shown.-\f[CR]aregister\f[R] ignores depth limits, so its final total will-always match a balance report with similar arguments.-.PP-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\[aq]s real\-world running balance.-.PP-An example: this shows the transactions and historical running balance-during july, in the first account whose name contains-\[dq]checking\[dq]:-.IP-.EX-$ hledger areg checking date:jul-.EE-.PP-Each \f[CR]aregister\f[R] line item shows:-.IP \[bu] 2-the transaction\[aq]s date (or the relevant posting\[aq]s date if-different, see below)-.IP \[bu] 2-the names of all the other account(s) involved in this transaction-(probably abbreviated)-.IP \[bu] 2-the total change to this account\[aq]s balance from this transaction-.IP \[bu] 2-the account\[aq]s historical running balance after this transaction.-.PP-Transactions making a net change of zero are not shown by default; add-the \f[CR]\-E/\-\-empty\f[R] flag to show them.-.PP-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 \f[CR]\-\-align\-all\f[R] flag.-.PP-This command also supports the output destination and output format-options.-The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],-\f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), and \f[CR]json\f[R].-.SS 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\[aq]s postings may be within the report-period.-To resolve this, aregister shows the earliest of the transaction\[aq]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\[aq]s last posting) be inaccurate.-Use \f[CR]register \-H\f[R] if you need to see the individual postings.-.PP-There is also a \f[CR]\-\-txn\-dates\f[R] flag, which filters strictly-by transaction date, ignoring posting dates.-This too can cause an inaccurate running balance.-.SS balance-(bal)-.PP-Show accounts and their balances.-.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-changes and more, during one time period or many.-Generally it shows a table, with rows representing accounts, and columns-representing periods.-.PP-Note there are some higher\-level variants of the \f[CR]balance\f[R]-command with convenient defaults, which can be simpler to use:-\f[CR]balancesheet\f[R], \f[CR]balancesheetequity\f[R],-\f[CR]cashflow\f[R] and \f[CR]incomestatement\f[R].-When you need more control, then use \f[CR]balance\f[R].-.SS balance features-Here\[aq]s a quick overview of the \f[CR]balance\f[R] command\[aq]s-features, followed by more detailed descriptions and examples.-Many of these work with the higher\-level commands as well.-.PP-\f[CR]balance\f[R] can show..-.IP \[bu] 2-accounts as a list (\f[CR]\-l\f[R]) or a tree (\f[CR]\-t\f[R])-.IP \[bu] 2-optionally depth\-limited (\f[CR]\-[1\-9]\f[R])-.IP \[bu] 2-sorted by declaration order and name, or by amount-.PP-\&..and their..-.IP \[bu] 2-balance changes (the default)-.IP \[bu] 2-or actual and planned balance changes (\f[CR]\-\-budget\f[R])-.IP \[bu] 2-or value of balance changes (\f[CR]\-V\f[R])-.IP \[bu] 2-or change of balance values (\f[CR]\-\-valuechange\f[R])-.IP \[bu] 2-or unrealised capital gain/loss (\f[CR]\-\-gain\f[R])-.IP \[bu] 2-or balance changes from sibling postings-(\f[CR]\-\-related\f[R]/\f[CR]\-r\f[R])-.IP \[bu] 2-or postings count (\f[CR]\-\-count\f[R])-.PP-\&..in..-.IP \[bu] 2-one time period (the whole journal period by default)-.IP \[bu] 2-or multiple periods (\f[CR]\-D\f[R], \f[CR]\-W\f[R], \f[CR]\-M\f[R],-\f[CR]\-Q\f[R], \f[CR]\-Y\f[R], \f[CR]\-p INTERVAL\f[R])-.PP-\&..either..-.IP \[bu] 2-per period (the default)-.IP \[bu] 2-or accumulated since report start date (\f[CR]\-\-cumulative\f[R])-.IP \[bu] 2-or accumulated since account creation (\f[CR]\-\-historical/\-H\f[R])-.PP-\&..possibly converted to..-.IP \[bu] 2-cost-(\f[CR]\-\-value=cost[,COMM]\f[R]/\f[CR]\-\-cost\f[R]/\f[CR]\-B\f[R])-.IP \[bu] 2-or market value, as of transaction dates-(\f[CR]\-\-value=then[,COMM]\f[R])-.IP \[bu] 2-or at period ends (\f[CR]\-\-value=end[,COMM]\f[R])-.IP \[bu] 2-or now (\f[CR]\-\-value=now\f[R])-.IP \[bu] 2-or at some other date (\f[CR]\-\-value=YYYY\-MM\-DD\f[R])-.PP-\&..with..-.IP \[bu] 2-totals (\f[CR]\-T\f[R]), averages (\f[CR]\-A\f[R]), percentages-(\f[CR]\-%\f[R]), inverted sign (\f[CR]\-\-invert\f[R])-.IP \[bu] 2-rows and columns swapped (\f[CR]\-\-transpose\f[R])-.IP \[bu] 2-another field used as account name (\f[CR]\-\-pivot\f[R])-.IP \[bu] 2-custom\-formatted line items (single\-period reports only)-(\f[CR]\-\-format\f[R])-.IP \[bu] 2-commodities displayed on the same line or multiple lines-(\f[CR]\-\-layout\f[R])-.PP-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].-In \f[CR]txt\f[R] output in a colour\-supporting terminal, negative-amounts are shown in red.-.SS Simple balance report-With no arguments, \f[CR]balance\f[R] 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.-(\[dq]Simple\[dq] here means just one column of numbers, covering a-single period.-You can also have multi\-period reports, described later.)-.PP-For real\-world accounts, these numbers will normally be their end-balance at the end of the journal period; more on this below.-.PP-Accounts are sorted by declaration order if any, and then alphabetically-by account name.-For instance (using examples/sample.journal):-.IP-.EX-$ 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  -.EE-.PP-Accounts with a zero balance (and no non\-zero subaccounts, in tree mode-\- see below) are hidden by default.-Use \f[CR]\-E/\-\-empty\f[R] to show them (revealing-\f[CR]assets:bank:checking\f[R] here):-.IP-.EX-$ 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  -.EE-.PP-The total of the amounts displayed is shown as the last line, unless-\f[CR]\-N\f[R]/\f[CR]\-\-no\-total\f[R] is used.-.SS Balance report line format-For single\-period balance reports displayed in the terminal (only), you-can use \f[CR]\-\-format FMT\f[R] to customise the format and content of-each line.-Eg:-.IP-.EX-$ hledger \-f examples/sample.journal balance \-\-format \[dq]%20(account) %12(total)\[dq]-              assets          $\-1-         bank:saving           $1-                cash          $\-2-            expenses           $2-                food           $1-            supplies           $1-              income          $\-2-               gifts          $\-1-              salary          $\-1-   liabilities:debts           $1-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--                                0-.EE-.PP-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:-.PP-\f[CR]%[MIN][.MAX](FIELDNAME)\f[R]-.IP \[bu] 2-MIN pads with spaces to at least this width (optional)-.IP \[bu] 2-MAX truncates at this width (optional)-.IP \[bu] 2-FIELDNAME must be enclosed in parentheses, and can be one of:-.RS 2-.IP \[bu] 2-\f[CR]depth_spacer\f[R] \- a number of spaces equal to the account\[aq]s-depth, or if MIN is specified, MIN * depth spaces.-.IP \[bu] 2-\f[CR]account\f[R] \- the account\[aq]s name-.IP \[bu] 2-\f[CR]total\f[R] \- the account\[aq]s balance/posted total, right-justified-.RE-.PP-Also, FMT can begin with an optional prefix to control how-multi\-commodity amounts are rendered:-.IP \[bu] 2-\f[CR]%_\f[R] \- render on multiple lines, bottom\-aligned (the default)-.IP \[bu] 2-\f[CR]%\[ha]\f[R] \- render on multiple lines, top\-aligned-.IP \[bu] 2-\f[CR]%,\f[R] \- render on one line, comma\-separated-.PP-There are some quirks.-Eg in one\-line mode, \f[CR]%(depth_spacer)\f[R] has no effect, instead-\f[CR]%(account)\f[R] has indentation built in.-\ Experimentation may be needed to get pleasing results.-.PP-Some example formats:-.IP \[bu] 2-\f[CR]%(total)\f[R] \- the account\[aq]s total-.IP \[bu] 2-\f[CR]%\-20.20(account)\f[R] \- the account\[aq]s name, left justified,-padded to 20 characters and clipped at 20 characters-.IP \[bu] 2-\f[CR]%,%\-50(account)  %25(total)\f[R] \- account name padded to 50-characters, total padded to 20 characters, with multiple commodities-rendered on one line-.IP \[bu] 2-\f[CR]%20(total)  %2(depth_spacer)%\-(account)\f[R] \- the default-format for the single\-column balance report-.SS 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:-.IP-.EX-$ hledger \-f examples/sample.journal bal \-\-cleared assets date:200806-                 $\-2  assets:cash-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--                 $\-2  -.EE-.SS List or tree mode-By default, or with \f[CR]\-l/\-\-flat\f[R], accounts are shown as a-flat list with their full names visible, as in the examples above.-.PP-With \f[CR]\-t/\-\-tree\f[R], the account hierarchy is shown, with-subaccounts\[aq] \[dq]leaf\[dq] names indented below their parent:-.IP-.EX-$ 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-.EE-.PP-Notes:-.IP \[bu] 2-\[dq]Boring\[dq] accounts are combined with their subaccount for more-compact output, unless \f[CR]\-\-no\-elide\f[R] is used.-Boring accounts have no balance of their own and just one subaccount (eg-\f[CR]assets:bank\f[R] and \f[CR]liabilities\f[R] above).-.IP \[bu] 2-All balances shown are \[dq]inclusive\[dq], 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\[aq]s final total is the sum of the top\-level-balances shown, not of all the balances shown.-.IP \[bu] 2-Each group of sibling accounts (ie, under a common parent) is sorted-separately.-.SS Depth limiting-With a \f[CR]depth:NUM\f[R] query, or \f[CR]\-\-depth NUM\f[R] option,-or just \f[CR]\-NUM\f[R] (eg: \f[CR]\-3\f[R]) 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.-.PP-Account balances at the depth limit always include the balances from any-deeper subaccounts (even in list mode).-Eg, limiting to depth 1:-.IP-.EX-$ hledger \-f examples/sample.journal balance \-1-                 $\-1  assets-                  $2  expenses-                 $\-2  income-                  $1  liabilities-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--                   0  -.EE-.SS Dropping top\-level accounts-You can also hide one or more top\-level account name parts, using-\f[CR]\-\-drop NUM\f[R].-This can be useful for hiding repetitive top\-level account names:-.IP-.EX-$ hledger \-f examples/sample.journal bal expenses \-\-drop 1-                  $1  food-                  $1  supplies-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--                  $2  -.EE-.PP-.SS Showing declared accounts-With \f[CR]\-\-declared\f[R], 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-\f[CR]\-E/\-\-empty\f[R] to see them.)-.PP-More precisely, \f[I]leaf\f[R] declared accounts (with no subaccounts)-will be included, since those are usually the more useful in reports.-.PP-The idea of this is to be able to see a useful \[dq]complete\[dq]-balance report, even when you don\[aq]t have transactions in all of your-declared accounts yet.-.SS Sorting by amount-With \f[CR]\-S/\-\-sort\-amount\f[R], accounts with the largest (most-positive) balances are shown first.-Eg: \f[CR]hledger bal expenses \-MAS\f[R] 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).-.PP-Revenues and liability balances are typically negative, however, so-\f[CR]\-S\f[R] shows these in reverse order.-To work around this, you can add \f[CR]\-\-invert\f[R] to flip the-signs.-(Or, use one of the higher\-level reports, which flip the sign-automatically.-Eg: \f[CR]hledger incomestatement \-MAS\f[R]).-.PP-.SS Percentages-With \f[CR]\-%/\-\-percent\f[R], balance reports show each account\[aq]s-value expressed as a percentage of the (column) total.-.PP-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:-.IP-.EX-$ hledger bal \-% amt:\[ga]>0\[ga]-$ hledger bal \-% amt:\[ga]<0\[ga]-.EE-.PP-Similarly, if the amounts in a column have mixed commodities, convert-them to one commodity with \f[CR]\-B\f[R], \f[CR]\-V\f[R],-\f[CR]\-X\f[R] or \f[CR]\-\-value\f[R], or make a separate report for-each commodity:-.IP-.EX-$ hledger bal \-% cur:\[rs]\[rs]$-$ hledger bal \-% cur:€-.EE-.SS Multi\-period balance report-With a report interval (set by the \f[CR]\-D/\-\-daily\f[R],-\f[CR]\-W/\-\-weekly\f[R], \f[CR]\-M/\-\-monthly\f[R],-\f[CR]\-Q/\-\-quarterly\f[R], \f[CR]\-Y/\-\-yearly\f[R], or-\f[CR]\-p/\-\-period\f[R] flag), \f[CR]balance\f[R] shows a tabular-report, with columns representing successive time periods (and a title):-.IP-.EX-$ 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 -.EE-.PP-Notes:-.IP \[bu] 2-The report\[aq]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).-.IP \[bu] 2-Leading and trailing periods (columns) containing all zeroes are not-shown, unless \f[CR]\-E/\-\-empty\f[R] is used.-.IP \[bu] 2-Accounts (rows) containing all zeroes are not shown, unless-\f[CR]\-E/\-\-empty\f[R] is used.-.IP \[bu] 2-Amounts with many commodities are shown in abbreviated form, unless-\f[CR]\-\-no\-elide\f[R] is used.-.IP \[bu] 2-Average and/or total columns can be added with the-\f[CR]\-A/\-\-average\f[R] and \f[CR]\-T/\-\-row\-total\f[R] flags.-.IP \[bu] 2-The \f[CR]\-\-transpose\f[R] flag can be used to exchange rows and-columns.-.IP \[bu] 2-The \f[CR]\-\-pivot FIELD\f[R] option causes a different transaction-field to be used as \[dq]account name\[dq].-See PIVOTING.-.PP-Multi\-period reports with many periods can be too wide for easy viewing-in the terminal.-Here are some ways to handle that:-.IP \[bu] 2-Hide the totals row with \f[CR]\-N/\-\-no\-total\f[R]-.IP \[bu] 2-Filter to a single currency with \f[CR]cur:\f[R]-.IP \[bu] 2-Convert to a single currency with-\f[CR]\-V [\-\-infer\-market\-price]\f[R]-.IP \[bu] 2-Use a more compact layout like \f[CR]\-\-layout=bare\f[R]-.IP \[bu] 2-Maximize the terminal window-.IP \[bu] 2-Reduce the terminal\[aq]s font size-.IP \[bu] 2-View with a pager like less, eg:-\f[CR]hledger bal \-D \-\-color=yes | less \-RS\f[R]-.IP \[bu] 2-Output as CSV and use a CSV viewer like visidata-(\f[CR]hledger bal \-D \-O csv | vd \-f csv\f[R]), Emacs\[aq] csv\-mode-(\f[CR]M\-x csv\-mode, C\-c C\-a\f[R]), or a spreadsheet-(\f[CR]hledger bal \-D \-o a.csv && open a.csv\f[R])-.IP \[bu] 2-Output as HTML and view with a browser:-\f[CR]hledger bal \-D \-o a.html && open a.html\f[R]-.SS Balance change, end balance-It\[aq]s important to be clear on the meaning of the numbers shown in-balance reports.-Here is some terminology we use:-.PP-A \f[B]\f[BI]balance change\f[B]\f[R] is the net amount added to, or-removed from, an account during some period.-.PP-An \f[B]\f[BI]end balance\f[B]\f[R] is the amount accumulated in an-account as of some date (and some time, but hledger doesn\[aq]t store-that; assume end of day in your timezone).-It is the sum of previous balance changes.-.PP-We call it a \f[B]\f[BI]historical end balance\f[B]\f[R] if it includes-all balance changes since the account was created.-For a real world account, this means it will match the \[dq]historical-record\[dq], eg the balances reported in your bank statements or bank-web UI.-(If they are correct!)-.PP-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.-.PP-\f[CR]balance\f[R] shows balance changes by default.-To see accurate historical end balances:-.IP "1." 3-Initialise account starting balances with an \[dq]opening balances\[dq]-transaction (a transfer from equity to the account), unless the journal-covers the account\[aq]s full lifetime.-.IP "2." 3-Include all of of the account\[aq]s prior postings in the report, by not-specifying a report start date, or by using the-\f[CR]\-H/\-\-historical\f[R] flag.-(\f[CR]\-H\f[R] causes report start date to be ignored when summing-postings.)-.SS 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\[aq]t worry \- this is for-advanced reporting, and it does take time and experimentation to get-familiar with all the report modes.-.PP-There are three important option groups:-.PP-\f[CR]hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] ...\f[R]-.SS Calculation type-The basic calculation to perform for each table cell.-It is one of:-.IP \[bu] 2-\f[CR]\-\-sum\f[R] : sum the posting amounts (\f[B]default\f[R])-.IP \[bu] 2-\f[CR]\-\-budget\f[R] : sum the amounts, but also show the budget goal-amount (for each account/period)-.IP \[bu] 2-\f[CR]\-\-valuechange\f[R] : show the change in period\-end historical-balance values (caused by deposits, withdrawals, and/or market price-fluctuations)-.IP \[bu] 2-\f[CR]\-\-gain\f[R] : show the unrealised capital gain/loss, (the-current valued balance minus each amount\[aq]s original cost)-.IP \[bu] 2-\f[CR]\-\-count\f[R] : show the count of postings-.SS Accumulation type-How amounts should accumulate across a report\[aq]s subperiods/columns.-Another way to say it: which time period\[aq]s postings should-contribute to each cell\[aq]s calculation.-It is one of:-.IP \[bu] 2-\f[CR]\-\-change\f[R] : calculate with postings from column start to-column end, ie \[dq]just this column\[dq].-Typically used to see revenues/expenses.-(\f[B]default for balance, cashflow, incomestatement\f[R])-.IP \[bu] 2-\f[CR]\-\-cumulative\f[R] : calculate with postings from report start to-column end, ie \[dq]previous columns plus this column\[dq].-Typically used to show changes accumulated since the report\[aq]s start-date.-Not often used.-.IP \[bu] 2-\f[CR]\-\-historical/\-H\f[R] : calculate with postings from journal-start to column end, ie \[dq]all postings from before report start date-until this column\[aq]s end\[dq].-Typically used to see historical end balances of-assets/liabilities/equity.-(\f[B]default for balancesheet, balancesheetequity\f[R])-.SS Valuation type-Which kind of value or cost conversion should be applied, if any, before-displaying the report.-It is one of:-.IP \[bu] 2-no valuation type : don\[aq]t convert to cost or value-(\f[B]default\f[R])-.IP \[bu] 2-\f[CR]\-\-value=cost[,COMM]\f[R] : convert amounts to cost (then-optionally to some other commodity)-.IP \[bu] 2-\f[CR]\-\-value=then[,COMM]\f[R] : convert amounts to market value on-transaction dates-.IP \[bu] 2-\f[CR]\-\-value=end[,COMM]\f[R] : convert amounts to market value on-period end date(s)-.PD 0-.P-.PD-(\f[B]default with \f[CB]\-\-valuechange\f[B], \f[CB]\-\-gain\f[B]\f[R])-.IP \[bu] 2-\f[CR]\-\-value=now[,COMM]\f[R] : convert amounts to market value on-today\[aq]s date-.IP \[bu] 2-\f[CR]\-\-value=YYYY\-MM\-DD[,COMM]\f[R] : convert amounts to market-value on another date-.PP-or one of the equivalent simpler flags:-.IP \[bu] 2-\f[CR]\-B/\-\-cost\f[R] : like \-\-value=cost (though, note \-\-cost and-\-\-value are independent options which can both be used at once)-.IP \[bu] 2-\f[CR]\-V/\-\-market\f[R] : like \-\-value=end-.IP \[bu] 2-\f[CR]\-X COMM/\-\-exchange COMM\f[R] : like \-\-value=end,COMM-.PP-See Cost reporting and Value reporting for more about these.-.SS 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:-.IP \[bu] 2-\f[CR]\-\-valuechange\f[R] implies \f[CR]\-\-value=end\f[R]-.IP \[bu] 2-\f[CR]\-\-valuechange\f[R] makes \f[CR]\-\-change\f[R] the default when-used with the \f[CR]balancesheet\f[R]/\f[CR]balancesheetequity\f[R]-commands-.IP \[bu] 2-\f[CR]\-\-cumulative\f[R] or \f[CR]\-\-historical\f[R] disables-\f[CR]\-\-row\-total/\-T\f[R]-.PP-For reference, here is what the combinations of accumulation and-valuation show:-.PP-.TS-tab(@);-lw(7.9n) lw(16.4n) lw(16.9n) lw(15.1n) lw(13.7n).-T{-Valuation:> Accumulation:v-T}@T{-no valuation-T}@T{-\f[CR]\-\-value= then\f[R]-T}@T{-\f[CR]\-\-value= end\f[R]-T}@T{-\f[CR]\-\-value= YYYY\-MM\-DD /now\f[R]-T}-_-T{-\f[CR]\-\-change\f[R]-T}@T{-change in period-T}@T{-sum of posting\-date market values in period-T}@T{-period\-end value of change in period-T}@T{-DATE\-value of change in period-T}-T{-\f[CR]\-\-cumulative\f[R]-T}@T{-change from report start to period end-T}@T{-sum of posting\-date market values from report start to period end-T}@T{-period\-end value of change from report start to period end-T}@T{-DATE\-value of change from report start to period end-T}-T{-\f[CR]\-\-historical /\-H\f[R]-T}@T{-change from journal start to period end (historical end balance)-T}@T{-sum of posting\-date market values from journal start to period end-T}@T{-period\-end value of change from journal start to period end-T}@T{-DATE\-value of change from journal start to period end-T}-.TE-.SS Budget report-The \f[CR]\-\-budget\f[R] report type is like a regular balance report,-but with two main differences:-.IP \[bu] 2-Budget goals and performance percentages are also shown, in brackets-.IP \[bu] 2-Accounts which don\[aq]t have budget goals are hidden by default.-.PP-This is useful for comparing planned and actual income, expenses, time-usage, etc.-.PP-Periodic transaction rules are used to define budget goals.-For example, here\[aq]s a periodic rule defining monthly goals for bus-travel and food expenses:-.IP-.EX-;; Budget-\[ti] monthly-  (expenses:bus)              $30-  (expenses:food)            $400-.EE-.PP-After recording some actual expenses,-.IP-.EX-;; 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-.EE-.PP-we can see a budget report like this:-.IP-.EX-$ 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] -.EE-.PP-This is \[dq]goal\-based budgeting\[dq]; you define goals for accounts-and periods, often recurring, and hledger shows performance relative to-the goals.-This contrasts with \[dq]envelope budgeting\[dq], 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.-.SS Using the budget report-Historically this report has been confusing and fragile.-hledger\[aq]s version should be relatively robust and intuitive, but you-may still find surprises.-Here are more notes to help with learning and troubleshooting.-.IP \[bu] 2-In the above example, \f[CR]expenses:bus\f[R] and-\f[CR]expenses:food\f[R] are shown because they have budget goals during-the report period.-.IP \[bu] 2-Their parent \f[CR]expenses\f[R] is also shown, with budget goals-aggregated from the children.-.IP \[bu] 2-The subaccounts \f[CR]expenses:food:groceries\f[R] and-\f[CR]expenses:food:dining\f[R] are not shown since they have no budget-goal of their own, but they contribute to \f[CR]expenses:food\f[R]\[aq]s-actual amount.-.IP \[bu] 2-Unbudgeted accounts \f[CR]expenses:movies\f[R] and-\f[CR]expenses:gifts\f[R] are also not shown, but they contribute to-\f[CR]expenses\f[R]\[aq]s actual amount.-.IP \[bu] 2-The other unbudgeted accounts \f[CR]income\f[R] and-\f[CR]assets:bank:checking\f[R] are grouped as \f[CR]<unbudgeted>\f[R].-.IP \[bu] 2-\f[CR]\-\-depth\f[R] or \f[CR]depth:\f[R] can be used to limit report-depth in the usual way (but will not reveal unbudgeted subaccounts).-.IP \[bu] 2-Amounts are always inclusive of subaccounts (even in-\f[CR]\-l/\-\-list\f[R] mode).-.IP \[bu] 2-Numbers displayed in a \-\-budget report will not always agree with the-totals, because of hidden unbudgeted accounts; this is normal.-\f[CR]\-E/\-\-empty\f[R] can be used to reveal the hidden accounts.-.IP \[bu] 2-In the periodic rules used for setting budget goals, unbalanced postings-are convenient.-.IP \[bu] 2-You can filter budget reports with the usual queries, eg to focus on-particular accounts.-It\[aq]s common to restrict them to just expenses.-(The \f[CR]<unbudgeted>\f[R] account is occasionally hard to exclude;-this is because of date surprises, discussed below.)-.IP \[bu] 2-When you have multiple currencies, you may want to convert them to one-(\f[CR]\-X COMM \-\-infer\-market\-prices\f[R]) and/or show just one at-a time (\f[CR]cur:COMM\f[R]).-If you do need to show multiple currencies at once,-\f[CR]\-\-layout bare\f[R] can be helpful.-.IP \[bu] 2-You can \[dq]roll over\[dq] amounts (actual and budgeted) to the next-period with \f[CR]\-\-cumulative\f[R].-.PP-See also: https://hledger.org/budgeting.html.-.SS 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 \f[CR]expenses:food\f[R] budget.-(Also the \f[CR]<unbudgeted>\f[R] account should be excluded by the-\f[CR]expenses\f[R] query, but isn\[aq]t.):-.IP-.EX-\[ti] monthly in 2020-  (expenses:food)  $500--2020\-01\-15-  expenses:food    $400-  assets:checking-.EE-.IP-.EX-$ 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] -.EE-.PP-In this case, the budget goal transactions are generated on first days-of of month (this can be seen with-\f[CR]hledger print \-\-forecast tag:generated expenses\f[R]).-Whereas the report period defaults to just the 15th day of january (this-can be seen from the report table\[aq]s column headings).-.PP-To fix this kind of thing, be more explicit about the report period-(and/or the periodic rules\[aq] dates).-In this case, adding \f[CR]\-b 2020\f[R] does the trick.-.SS 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.-.PP-You can select a subset of periodic rules by providing an argument to-the \f[CR]\-\-budget\f[R] flag.-\f[CR]\-\-budget=DESCPAT\f[R] 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.-.SS Budgeting vs forecasting-\f[CR]\-\-forecast\f[R] and \f[CR]\-\-budget\f[R] 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:-.PP-.TS-tab(@);-lw(38.2n) lw(31.8n).-T{-\-\-forecast-T}@T{-\-\-budget-T}-_-T{-is a general option; it enables forecasting with all reports-T}@T{-is a balance command option; it selects the balance report\[aq]s budget-mode-T}-T{-generates visible transactions which appear in reports-T}@T{-generates invisible transactions which produce goal amounts-T}-T{-generates forecast transactions from after the last regular transaction,-to the end of the report period; or with an argument-\f[CR]\-\-forecast=PERIODEXPR\f[R] generates them throughout the-specified period, both optionally restricted by periods specified in the-periodic transaction rules-T}@T{-generates budget goal transactions throughout the report period,-optionally restricted by periods specified in the periodic transaction-rules-T}-T{-uses all periodic rules-T}@T{-uses all periodic rules; or with an argument-\f[CR]\-\-budget=DESCPAT\f[R] uses just the rules matched by DESCPAT-T}-.TE-.SS Balance report layout-The \f[CR]\-\-layout\f[R] 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:-.IP \[bu] 2-\f[CR]\-\-layout=wide[,WIDTH]\f[R]: commodities are shown on a single-line, optionally elided to WIDTH-.IP \[bu] 2-\f[CR]\-\-layout=tall\f[R]: each commodity is shown on a separate line-.IP \[bu] 2-\f[CR]\-\-layout=bare\f[R]: commodity symbols are in their own column,-amounts are bare numbers-.IP \[bu] 2-\f[CR]\-\-layout=tidy\f[R]: data is normalised to easily\-consumed-\[dq]tidy\[dq] form, with one row per data value-.PP-Here are the \f[CR]\-\-layout\f[R] modes supported by each output format-Only CSV output supports all of them:-.PP-.TS-tab(@);-l l l l l l.-T{-\--T}@T{-txt-T}@T{-csv-T}@T{-html-T}@T{-json-T}@T{-sql-T}-_-T{-wide-T}@T{-Y-T}@T{-Y-T}@T{-Y-T}@T{-T}@T{-T}-T{-tall-T}@T{-Y-T}@T{-Y-T}@T{-Y-T}@T{-T}@T{-T}-T{-bare-T}@T{-Y-T}@T{-Y-T}@T{-Y-T}@T{-T}@T{-T}-T{-tidy-T}@T{-T}@T{-Y-T}@T{-T}@T{-T}@T{-T}-.TE-.PP-Examples:-.SS Wide layout-With many commodities, reports can be very wide:-.IP-.EX-$ 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 -.EE-.PP-A width limit reduces the width, but some commodities will be hidden:-.IP-.EX-$ 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.. -.EE-.SS Tall layout-Each commodity gets a new line (may be different in each column), and-account names are repeated:-.IP-.EX-$ 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 -.EE-.SS Bare layout-Commodity symbols are kept in one column, each commodity has its own-row, amounts are bare numbers, account names are repeated:-.IP-.EX-$ 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 -.EE-.PP-Bare layout also affects CSV output, which is useful for producing data-that is easier to consume, eg for making charts:-.IP-.EX-$ hledger \-f examples/bcexample.hledger bal assets:us:etrade \-3 \-O csv \-\-layout=bare-\[dq]account\[dq],\[dq]commodity\[dq],\[dq]balance\[dq]-\[dq]Assets:US:ETrade\[dq],\[dq]GLD\[dq],\[dq]70.00\[dq]-\[dq]Assets:US:ETrade\[dq],\[dq]ITOT\[dq],\[dq]17.00\[dq]-\[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]-.EE-.PP-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 \f[CR]hledger\-bar\f[R] confusingly (workaround: add a-\f[CR]cur:\f[R] query to exclude the no\-symbol row).-.SS Tidy layout-This produces normalised \[dq]tidy data\[dq] (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:-.IP-.EX-$ hledger \-f examples/bcexample.hledger bal assets:us:etrade \-3 \-Y \-O csv \-\-layout=tidy-\[dq]account\[dq],\[dq]period\[dq],\[dq]start_date\[dq],\[dq]end_date\[dq],\[dq]commodity\[dq],\[dq]value\[dq]-\[dq]Assets:US:ETrade\[dq],\[dq]2012\[dq],\[dq]2012\-01\-01\[dq],\[dq]2012\-12\-31\[dq],\[dq]GLD\[dq],\[dq]0\[dq]-\[dq]Assets:US:ETrade\[dq],\[dq]2012\[dq],\[dq]2012\-01\-01\[dq],\[dq]2012\-12\-31\[dq],\[dq]ITOT\[dq],\[dq]10.00\[dq]-\[dq]Assets:US:ETrade\[dq],\[dq]2012\[dq],\[dq]2012\-01\-01\[dq],\[dq]2012\-12\-31\[dq],\[dq]USD\[dq],\[dq]337.18\[dq]-\[dq]Assets:US:ETrade\[dq],\[dq]2012\[dq],\[dq]2012\-01\-01\[dq],\[dq]2012\-12\-31\[dq],\[dq]VEA\[dq],\[dq]12.00\[dq]-\[dq]Assets:US:ETrade\[dq],\[dq]2012\[dq],\[dq]2012\-01\-01\[dq],\[dq]2012\-12\-31\[dq],\[dq]VHT\[dq],\[dq]106.00\[dq]-\[dq]Assets:US:ETrade\[dq],\[dq]2013\[dq],\[dq]2013\-01\-01\[dq],\[dq]2013\-12\-31\[dq],\[dq]GLD\[dq],\[dq]70.00\[dq]-\[dq]Assets:US:ETrade\[dq],\[dq]2013\[dq],\[dq]2013\-01\-01\[dq],\[dq]2013\-12\-31\[dq],\[dq]ITOT\[dq],\[dq]18.00\[dq]-\[dq]Assets:US:ETrade\[dq],\[dq]2013\[dq],\[dq]2013\-01\-01\[dq],\[dq]2013\-12\-31\[dq],\[dq]USD\[dq],\[dq]\-98.12\[dq]-\[dq]Assets:US:ETrade\[dq],\[dq]2013\[dq],\[dq]2013\-01\-01\[dq],\[dq]2013\-12\-31\[dq],\[dq]VEA\[dq],\[dq]10.00\[dq]-\[dq]Assets:US:ETrade\[dq],\[dq]2013\[dq],\[dq]2013\-01\-01\[dq],\[dq]2013\-12\-31\[dq],\[dq]VHT\[dq],\[dq]18.00\[dq]-\[dq]Assets:US:ETrade\[dq],\[dq]2014\[dq],\[dq]2014\-01\-01\[dq],\[dq]2014\-12\-31\[dq],\[dq]GLD\[dq],\[dq]0\[dq]-\[dq]Assets:US:ETrade\[dq],\[dq]2014\[dq],\[dq]2014\-01\-01\[dq],\[dq]2014\-12\-31\[dq],\[dq]ITOT\[dq],\[dq]\-11.00\[dq]-\[dq]Assets:US:ETrade\[dq],\[dq]2014\[dq],\[dq]2014\-01\-01\[dq],\[dq]2014\-12\-31\[dq],\[dq]USD\[dq],\[dq]4881.44\[dq]-\[dq]Assets:US:ETrade\[dq],\[dq]2014\[dq],\[dq]2014\-01\-01\[dq],\[dq]2014\-12\-31\[dq],\[dq]VEA\[dq],\[dq]14.00\[dq]-\[dq]Assets:US:ETrade\[dq],\[dq]2014\[dq],\[dq]2014\-01\-01\[dq],\[dq]2014\-12\-31\[dq],\[dq]VHT\[dq],\[dq]170.00\[dq]-.EE-.SS Some useful balance reports-Some frequently used \f[CR]balance\f[R] options/reports are:-.IP \[bu] 2-\f[CR]bal \-M revenues expenses\f[R]-.PD 0-.P-.PD-Show revenues/expenses in each month.-Also available as the \f[CR]incomestatement\f[R] command.-.IP \[bu] 2-\f[CR]bal \-M \-H assets liabilities\f[R]-.PD 0-.P-.PD-Show historical asset/liability balances at each month end.-Also available as the \f[CR]balancesheet\f[R] command.-.IP \[bu] 2-\f[CR]bal \-M \-H assets liabilities equity\f[R]-.PD 0-.P-.PD-Show historical asset/liability/equity balances at each month end.-Also available as the \f[CR]balancesheetequity\f[R] command.-.IP \[bu] 2-\f[CR]bal \-M assets not:receivable\f[R]-.PD 0-.P-.PD-Show changes to liquid assets in each month.-Also available as the \f[CR]cashflow\f[R] command.-.PP-Also:-.IP \[bu] 2-\f[CR]bal \-M expenses \-2 \-SA\f[R]-.PD 0-.P-.PD-Show monthly expenses summarised to depth 2 and sorted by average-amount.-.IP \[bu] 2-\f[CR]bal \-M \-\-budget expenses\f[R]-.PD 0-.P-.PD-Show monthly expenses and budget goals.-.IP \[bu] 2-\f[CR]bal \-M \-\-valuechange investments\f[R]-.PD 0-.P-.PD-Show monthly change in market value of investment assets.-.IP \[bu] 2-\f[CR]bal investments \-\-valuechange \-D date:lastweek amt:\[aq]>1000\[aq] \-STA [\-\-invert]\f[R]-.PD 0-.P-.PD-Show top gainers [or losers] last week-.SS balancesheet-(bs)-.PP-This command displays a balance sheet, showing historical ending-balances of asset and liability accounts.-(To see equity as well, use the balancesheetequity command.)-Amounts are shown with normal positive sign, as in conventional-financial statements.-.PP-This report shows accounts declared with the \f[CR]Asset\f[R],-\f[CR]Cash\f[R] or \f[CR]Liability\f[R] type (see account types).-Or if no such accounts are declared, it shows top\-level accounts named-\f[CR]asset\f[R] or \f[CR]liability\f[R] (case insensitive, plurals-allowed) and their subaccounts.-.PP-Example:-.IP-.EX-$ 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 -.EE-.PP-This command is a higher\-level variant of the \f[CR]balance\f[R]-command, and supports many of that command\[aq]s features, such as-multi\-period reports.-It is similar to \f[CR]hledger balance \-H assets liabilities\f[R], but-with smarter account detection, and liabilities displayed with their-sign flipped.-.PP-This command also supports the output destination and output format-options The output formats supported are \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]html\f[R], and-\f[CR]json\f[R].-.SS balancesheetequity-(bse)-.PP-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.-.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-account types).-Or if no such accounts are declared, it shows top\-level accounts named-\f[CR]asset\f[R], \f[CR]liability\f[R] or \f[CR]equity\f[R] (case-insensitive, plurals allowed) and their subaccounts.-.PP-Example:-.IP-.EX-$ 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 -.EE-.PP-This command is a higher\-level variant of the \f[CR]balance\f[R]-command, and supports many of that command\[aq]s features, such as-multi\-period reports.-It is similar to-\f[CR]hledger balance \-H assets liabilities equity\f[R], but with-smarter account detection, and liabilities/equity displayed with their-sign flipped.-.PP-This report is the easiest way to see if the accounting equation (A+L+E-= 0) is satisfied (after you have done a \f[CR]close \-\-retain\f[R] to-merge revenues and expenses with equity, and perhaps added-\f[CR]\-\-infer\-equity\f[R] to balance your commodity conversions).-.PP-This command also supports the output destination and output format-options The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],-\f[CR]tsv\f[R], \f[CR]html\f[R], and \f[CR]json\f[R].-.SS cashflow-(cf)-.PP-This command displays a (simple) cashflow statement, showing the inflows-and outflows affecting \[dq]cash\[dq] (ie, liquid, easily convertible)-assets.-Amounts are shown with normal positive sign, as in conventional-financial statements.-.PP-This report shows accounts declared with the \f[CR]Cash\f[R] type (see-account types).-Or if no such accounts are declared, it shows accounts-.IP \[bu] 2-under a top\-level account named \f[CR]asset\f[R] (case insensitive,-plural allowed)-.IP \[bu] 2-whose name contains some variation of \f[CR]cash\f[R], \f[CR]bank\f[R],-\f[CR]checking\f[R] or \f[CR]saving\f[R].-.PP-More precisely: all accounts matching this case insensitive regular-expression:-.PP-\f[CR]\[ha]assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$)\f[R]-.PP-and their subaccounts.-.PP-An example cashflow report:-.IP-.EX-$ hledger cashflow-Cashflow Statement 2008--                    || 2008 -====================++======- Cash flows         ||      -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-- assets:bank:saving ||   $1 - assets:cash        ||  $\-2 -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\--                    ||  $\-1 -.EE-.PP-This command is a higher\-level variant of the \f[CR]balance\f[R]-command, and supports many of that command\[aq]s features, such as-multi\-period reports.-It is similar to-\f[CR]hledger balance assets not:fixed not:investment not:receivable\f[R],-but with smarter account detection.-.PP-This command also supports the output destination and output format-options The output formats supported are \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]html\f[R], and-\f[CR]json\f[R].-.SS check-Check for various kinds of errors in your data.-.PP-hledger provides a number of built\-in error checks to help prevent-problems in your data.-Some of these are run automatically; or, you can use this-\f[CR]check\f[R] command to run them on demand, with no output and a-zero exit code if all is well.-Specify their names (or a prefix) as argument(s).-.PP-Some examples:-.IP-.EX-hledger check      # basic checks-hledger check \-s   # basic + strict checks-hledger check ordereddates payees  # basic + two other checks-.EE-.PP-If you are an Emacs user, you can also configure flycheck\-hledger to-run these checks, providing instant feedback as you edit the journal.-.PP-Here are the checks currently available:-.SS Default checks-These checks are run automatically by (almost) all hledger commands:-.IP \[bu] 2-\f[B]parseable\f[R] \- data files are in a supported format, with no-syntax errors and no invalid include directives.-.IP \[bu] 2-\f[B]autobalanced\f[R] \- all transactions are balanced, after-converting to cost.-Missing amounts and missing costs are inferred automatically where-possible.-.IP \[bu] 2-\f[B]assertions\f[R] \- all balance assertions in the journal are-passing.-(This check can be disabled with-\f[CR]\-I\f[R]/\f[CR]\-\-ignore\-assertions\f[R].)-.SS Strict checks-These additional checks are run when the-\f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R] (strict mode) flag is used.-Or, they can be run by giving their names as arguments to-\f[CR]check\f[R]:-.IP \[bu] 2-\f[B]balanced\f[R] \- all transactions are balanced after converting to-cost, without inferring missing costs.-If conversion costs are required, they must be explicit.-.IP \[bu] 2-\f[B]accounts\f[R] \- all account names used by transactions have been-declared-.IP \[bu] 2-\f[B]commodities\f[R] \- all commodity symbols used have been declared-.SS Other checks-These checks can be run only by giving their names as arguments to-\f[CR]check\f[R].-They are more specialised and not desirable for everyone:-.IP \[bu] 2-\f[B]ordereddates\f[R] \- transactions are ordered by date within each-file-.IP \[bu] 2-\f[B]payees\f[R] \- all payees used by transactions have been declared-.IP \[bu] 2-\f[B]recentassertions\f[R] \- all accounts with balance assertions have-a balance assertion within 7 days of their latest posting-.IP \[bu] 2-\f[B]tags\f[R] \- all tags used by transactions have been declared-.IP \[bu] 2-\f[B]uniqueleafnames\f[R] \- all account leaf names are unique-.SS Custom checks-A few more checks are are available as separate add\-on commands, in-https://github.com/simonmichael/hledger/tree/master/bin:-.IP \[bu] 2-\f[B]hledger\-check\-tagfiles\f[R] \- all tag values containing / (a-forward slash) exist as file paths-.IP \[bu] 2-\f[B]hledger\-check\-fancyassertions\f[R] \- more complex balance-assertions are passing-.PP-You could make similar scripts to perform your own custom checks.-See: Cookbook \-> Scripting.-.SS More about specific checks-\f[CR]hledger check recentassertions\f[R] will complain if any-balance\-asserted account has postings more than 7 days after its latest-balance assertion.-This aims to prevent the situation where you are regularly updating your-journal, but forgetting to check your balances against the real world,-then one day must dig back through months of data to find an error.-It assumes that adding a balance assertion requires/reminds you to check-the real\-world balance.-(That may not be true if you auto\-generate balance assertions from bank-data; in that case, I recommend to import transactions uncleared, and-when you manually review and clear them, also check the latest assertion-against the real\-world balance.)-.SS close-(equity)-.PP-\f[CR]close\f[R] generates several kinds of \[dq]closing\[dq] and/or-\[dq]opening\[dq] transactions, useful in certain situations, including-migrating balances to a new journal file, retaining earnings into-equity, consolidating balances, or viewing lots.-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.-.PP-\f[CR]close\f[R] currently has six modes, selected by a single mode-flag:-.SS close \-\-migrate-This is the most common mode.-It prints a \[dq]closing balances\[dq] transaction that zeroes out all-asset and liability balances (by default), and an opposite \[dq]opening-balances\[dq] transaction that restores them again.-The balancing account will be \f[CR]equity:opening/closing balances\f[R]-(or another specified by \f[CR]\-\-close\-acct\f[R] or-\f[CR]\-\-open\-acct\f[R]).-.PP-This is useful when migrating balances to a new journal file at the-start of a new year.-Essentially, you run-\f[CR]hledger close \-\-migrate=NEWYEAR \-e NEWYEAR\f[R] and then copy-the closing transaction to the end of the old file and the opening-transaction to the start of the new file.-The opening transaction sets correct starting balances in the new file-when it is used alone, and the closing transaction keeps balances-correct when you use both old and new files together, by cancelling out-the following opening transaction and preventing buildup of duplicated-opening balances.-Think of the closing/opening pair as \[dq]moving the balances into the-next file\[dq].-.PP-You can close a different set of accounts by providing a query.-Eg if you want to include equity, you can add-\f[CR]assets liabilities equity\f[R] or \f[CR]type:ALE\f[R] arguments.-(The balancing account is always excluded.)-Revenues and expenses usually are not migrated to a new file directly;-see \f[CR]\-\-retain\f[R] below.-.PP-The generated transactions will have a \f[CR]start:\f[R] tag, with its-value set to \f[CR]\-\-migrate\f[R]\[aq]s \f[CR]NEW\f[R] argument if-any, for easier matching or exclusion.-When \f[CR]NEW\f[R] is not specified, it will be inferred if possible by-incrementing a number (eg a year number) within the default-journal\[aq]s main file name.-The other modes behave similarly.-.SS close \-\-close-This prints just the closing balances transaction of-\f[CR]\-\-migrate\f[R].-It is the default behaviour if you specify no mode flag.-Using the customisation options below, you can move balances from any-set of accounts to a different account.-.SS close \-\-open-This prints just the opening balances transaction of-\f[CR]\-\-migrate\f[R].-It is similar to Ledger\[aq]s equity command.-.SS close \-\-assert-This prints a \[dq]closing balances\[dq] transaction (with-\f[CR]balances:\f[R] tag), that just declares balance assertions for the-current balances without changing them.-It could be useful as documention and to guard against changes.-.SS close \-\-assign-This prints an \[dq]opening balances\[dq] transaction that restores the-account balances using balance assignments.-Balance assignments work regardless of any previous balance, so a-preceding closing balances transaction is not needed.-.PP-However, omitting the closing balances transaction would unbalance-equity.-This is relatively harmless for personal reports, but it disturbs the-accounting equation, removing a source of error detection.-So \f[CR]\-\-migrate\f[R] is generally the best way to set to set-balances in new files, for now.-.SS close \-\-retain-This is like \f[CR]\-\-close\f[R] with different defaults: it prints a-\[dq]retain earnings\[dq] transaction (with \f[CR]retain:\f[R] tag),-that transfers revenue and expense balances to-\f[CR]equity:retained earnings\f[R].-.PP-This is a different kind of closing, called \[dq]retaining earnings\[dq]-or \[dq]closing the books\[dq]; it is traditionally performed by-businesses at the end of each accounting period, to consolidate revenues-and expenses into the main equity balance.-(\[dq]Revenues\[dq] and \[dq]expenses\[dq] are actually equity by-another name, kept separate temporarily for reporting purposes.)-.PP-In personal accounting you generally don\[aq]t need to do this, unless-you want the \f[CR]balancesheetequity\f[R] report to show a zero total,-demonstrating that the accounting equation (A\-L=E) is satisfied.-.SS close customisation-In all modes, the following things can be overridden:-.IP \[bu] 2-the accounts to be closed/opened, with account query arguments-.IP \[bu] 2-the balancing account, with \f[CR]\-\-close\-acct=ACCT\f[R] and/or-\f[CR]\-\-open\-acct=ACCT\f[R]-.IP \[bu] 2-the transaction descriptions, with \f[CR]\-\-close\-desc=DESC\f[R] and-\f[CR]\-\-open\-desc=DESC\f[R]-.IP \[bu] 2-the transaction\[aq]s tag value, with a \f[CR]\-\-MODE=NEW\f[R] option-argument-.IP \[bu] 2-the closing/opening dates, with \f[CR]\-e OPENDATE\f[R]-.PP-By default, the closing date is yesterday, or the journal\[aq]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 \f[CR]\-e 2024\f[R] means \[dq]close on 2023\-12\-31, open on-2024\-01\-01\[dq].-.PP-With \f[CR]\-\-x/\-\-explicit\f[R], 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 \f[CR]print \-x\f[R]).-.PP-With \f[CR]\-\-interleaved\f[R], each individual transfer is shown with-source and destination postings next to each other (perhaps useful for-troubleshooting).-.PP-With \f[CR]\-\-show\-costs\f[R], balances\[aq] 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.-\f[CR]close \-\-show\-costs\f[R] is currently the best way to view-investment lots with hledger.-(To move or dispose of lots, see the more capable-\f[CR]hledger\-move\f[R] script.)-.SS close and balance assertions-\f[CR]close\f[R] 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 \f[CR]\-I\f[R], or remove them if you prefer.-.PP-Single\-commodity, subaccount\-exclusive balance assertions-(\f[CR]=\f[R]) are generated by default.-This can be changed with \f[CR]\-\-assertion\-type=\[aq]==*\[aq]\f[R]-(eg).-.PP-When running \f[CR]close\f[R] you should probably avoid using-\f[CR]\-C\f[R], \f[CR]\-R\f[R], \f[CR]status:\f[R] (filtering by status-or realness) or \f[CR]\-\-auto\f[R] (generating postings), since the-generated balance assertions would then require these.-.PP-Transactions with multiple dates (eg posting dates) spanning the file-boundary also can disrupt the balance assertions:-.IP-.EX-2023\-12\-30 a purchase made in december, cleared in january-    expenses:food          5-    assets:bank:checking  \-5  ; date: 2023\-01\-02-.EE-.PP-To solve this you can transfer the money to and from a temporary-account, splitting the multi\-day transaction into two single\-day-transactions:-.IP-.EX-; 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\[aq]s transaction cleared-    equity:pending         5 = 0-    assets:bank:checking  \-5-.EE-.SS close examples-.SS Retain earnings-Record 2022\[aq]s revenues/expenses as retained earnings on-2022\-12\-31, appending the generated transaction to the journal:-.IP-.EX-$ hledger close \-\-retain \-f 2022.journal \-p 2022 >> 2022.journal-.EE-.PP-After this, to see 2022\[aq]s revenues and expenses you must exclude the-retain earnings transaction:-.IP-.EX-$ hledger \-f 2022.journal is not:desc:\[aq]retain earnings\[aq]-.EE-.SS Migrate balances to a new file-Close assets/liabilities on 2022\-12\-31 and re\-open them on-2023\-01\-01:-.IP-.EX-$ 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-.EE-.PP-After this, to see 2022\[aq]s end\-of\-year balances you must exclude-the closing balances transaction:-.IP-.EX-$ hledger \-f 2022.journal bs not:desc:\[aq]closing balances\[aq]-.EE-.PP-For more flexibility, it helps to tag closing and opening transactions-with eg \f[CR]start:NEWYEAR\f[R], then you can ensure correct balances-by excluding all opening/closing transactions except the first, like so:-.IP-.EX-$ hledger bs \-Y \-f 2021.j \-f 2022.j \-f 2023.j expr:\[aq]tag:start=2021 or not tag:start\[aq]-$ hledger bs \-Y \-f 2021.j \-f 2022.j           expr:\[aq]tag:start=2021 or not tag:start\[aq]-$ hledger bs \-Y \-f 2022.j \-f 2023.j           expr:\[aq]tag:start=2022 or not tag:start\[aq]-$ hledger bs \-Y \-f 2021.j                     expr:\[aq]tag:start=2021 or not tag:start\[aq]-$ hledger bs \-Y \-f 2022.j                     expr:\[aq]tag:start=2022 or not tag:start\[aq]-$ hledger bs \-Y \-f 2023.j                     # unclosed file, no query needed-.EE-.SS More detailed close examples-See examples/multi\-year.-.SS codes-List the codes seen in transactions, in the order parsed.-.PP-This command prints the value of each transaction\[aq]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.-.PP-Transactions aren\[aq]t required to have a code, and missing or empty-codes will not be shown by default.-With the \f[CR]\-E\f[R]/\f[CR]\-\-empty\f[R] flag, they will be printed-as blank lines.-.PP-You can add a query to select a subset of transactions.-.PP-Examples:-.IP-.EX-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-.EE-.IP-.EX-$ hledger codes-123-124-126-.EE-.IP-.EX-$ hledger codes \-E-123-124--126-.EE-.SS commodities-List all commodity/currency symbols used or declared in the journal.-.SS demo-Play demos of hledger usage in the terminal, if asciinema is installed.-.PP-Run this command with no argument to list the demos.-To play a demo, write its number or a prefix or substring of its title.-Tips:-.PP-Make your terminal window large enough to see the demo clearly.-.PP-Use the \-s/\-\-speed SPEED option to set your preferred playback speed,-eg \f[CR]\-s4\f[R] to play at 4x original speed or \f[CR]\-s.5\f[R] to-play at half speed.-The default speed is 2x.-.PP-Other asciinema options can be added following a double dash, eg-\f[CR]\-\- \-i.1\f[R] to limit pauses or \f[CR]\-\- \-h\f[R] to list-asciinema\[aq]s other options.-.PP-During playback, several keys are available: SPACE to pause/unpause, .-to step forward (while paused), CTRL\-c quit.-.PP-Examples:-.IP-.EX-$ hledger demo               # list available demos-$ hledger demo 1             # play the first demo at default speed (2x)-$ hledger demo install \-s4   # play the \[dq]install\[dq] demo at 4x speed-.EE-.SS descriptions-List the unique descriptions that appear in transactions.-.PP-This command lists the unique descriptions that appear in transactions,-in alphabetic order.-You can add a query to select a subset of transactions.-.PP-Example:-.IP-.EX-$ hledger descriptions-Store Name-Gas Station | Petrol-Person A-.EE-.SS diff-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.-.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-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.-.PP-Examples:-.IP-.EX-$ 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:-.EE-.SS files-List all files included in the journal.-With a REGEX argument, only file names matching the regular expression-(case sensitive) are shown.-.SS help-Show the hledger user manual in the terminal, with \f[CR]info\f[R],-\f[CR]man\f[R], or a pager.-With a TOPIC argument, open it at that topic if possible.-TOPIC can be any heading in the manual, or a heading prefix, case-insensitive.-Eg: \f[CR]commands\f[R], \f[CR]print\f[R], \f[CR]forecast\f[R],-\f[CR]journal\f[R], \f[CR]amount\f[R],-\f[CR]\[dq]auto postings\[dq]\f[R].-.PP-This command shows the hledger manual built in to your hledger version.-It can be useful when offline, or when you prefer the terminal to a web-browser, or when the appropriate hledger manual or viewing tools are not-installed on your system.-.PP-By default it chooses the best viewer found in $PATH, trying (in this-order): \f[CR]info\f[R], \f[CR]man\f[R], \f[CR]$PAGER\f[R],-\f[CR]less\f[R], \f[CR]more\f[R].-You can force the use of info, man, or a pager with the \f[CR]\-i\f[R],-\f[CR]\-m\f[R], or \f[CR]\-p\f[R] flags, If no viewer can be found, or-the command is run non\-interactively, it just prints the manual to-stdout.-.PP-If using \f[CR]info\f[R], note that version 6 or greater is needed for-TOPIC lookup.-If you are on mac you will likely have info 4.8, and should consider-installing a newer version, eg with \f[CR]brew install texinfo\f[R]-(#1770).-.PP-Examples-.IP-.EX-$ hledger help \-\-help      # show how the help command works-$ hledger help             # show the hledger manual with info, man or $PAGER-$ hledger help journal     # show the journal topic in the hledger manual-$ hledger help \-m journal  # show it with man, even if info is installed-.EE-.SS import-Read new transactions added to each FILE provided as arguments since-last run, and add them to the journal.-Or with \-\-dry\-run, just print the transactions that would be added.-Or with \-\-catchup, just mark all of the FILEs\[aq] current-transactions as imported, without importing them.-.PP-This command may append new transactions to the main journal file (which-should be in journal format).-Existing transactions are not changed.-This is one of the few hledger commands that writes to the journal file-(see also \f[CR]add\f[R]).-.PP-Unlike other hledger commands, with \f[CR]import\f[R] the journal file-is an output file, and will be modified, though only by appending-(existing data will not be changed).-The input files are specified as arguments, so to import one or more CSV-files to your main journal, you will run-\f[CR]hledger import bank.csv\f[R] or perhaps-\f[CR]hledger import *.csv\f[R].-.PP-Note you can import from any file format, though CSV files are the most-common import source, and these docs focus on that case.-.SS Deduplication-\f[CR]import\f[R] 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\[aq]s CSV includes the last three months of data, you-can download and \f[CR]import\f[R] it every month (or week, or day) and-only the new transactions will be imported each time.-.PP-It works as follows.-For each imported \f[CR]FILE\f[R] (usually CSV, but they could be any of-hledger\[aq]s input formats):-.IP \[bu] 2-It tries to recall the latest date seen previously, reading it from a-hidden \f[CR].latest.FILE\f[R] in the same directory.-.IP \[bu] 2-Then it processes \f[CR]FILE\f[R], ignoring any transactions on or-before the \[dq]latest seen\[dq] date.-.PP-And after a successful import, it updates the \f[CR].latest.FILE\f[R](s)-for next time (unless \f[CR]\-\-dry\-run\f[R] was used).-.PP-This is a limited kind of deduplication, let\[aq]s call it \[dq]date-skipping\[dq].-Within each input file, it avoids reprocessing the same dates across-successive runs.-This is a simple system that works for most real\-world CSV files; it-assumes these are true, or true enough:-.IP "1." 3-new items always have the newest dates-.IP "2." 3-item dates are stable across successive downloads-.IP "3." 3-the order of same\-date items is stable across downloads-.IP "4." 3-the name of the input file is stable across downloads-.PP-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, and in old transactions it doesn\[aq]t matter.-And remember you can use CSV rules files as input, which is one way to-ensure a stable file name.-.PP-\f[CR]import\f[R] doesn\[aq]t detect other kinds of duplication, such as-duplicate transactions within a single run.-(In part, because legitimate duplicate transactions can easily occur in-real\-world data.)-So, say you downloaded but forgot to import \f[CR]bank.1.csv\f[R], and a-week later you downloaded \f[CR]bank.2.csv\f[R] with overlapping data.-Now you should not import both of these at once-(\f[CR]hledger import bank.1.csv bank.2.csv\f[R]); the overlapping-transactions which appear twice would not be deduplicated since this is-considered a single import.-Instead, import these files one at a time, and also use the same-filename each time for a common \[dq]latest seen\[dq] state:-.IP-.EX-$ mv bank.1.csv bank.csv; hledger import bank.csv-$ mv bank.2.csv bank.csv; hledger import bank.csv-.EE-.PP-Normally you can ignore the \f[CR].latest.*\f[R] files, but if needed,-you can delete them (to make all transactions unseen), or-construct/modify them (to catch up to a certain date).-The format is just a single ISO\-format date (\f[CR]YYYY\-MM\-DD\f[R]),-possibly repeated on multiple lines.-It means \[dq]I have seen transactions up to this date, and this many of-them occurring on that date\[dq].-.PP-\f[CR]hledger print \-\-new\f[R] also uses and updates these-\f[CR].latest.*\f[R] files, but it is less often used.-.PP-Related: CSV > Working with CSV > Deduplicating, importing.-.SS Import testing-With \f[CR]\-\-dry\-run\f[R], 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:-.IP-.EX-$ hledger import \-\-dry bank.csv | hledger \-f\- \-I print unknown-.EE-.PP-or (live updating):-.IP-.EX-$ ls bank.csv* | entr bash \-c \[aq]echo ====; hledger import \-\-dry bank.csv | hledger \-f\- \-I print unknown\[aq]-.EE-.PP-Note: when importing from multiple files at once, it\[aq]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.-.SS Importing balance assignments-Entries added by import will have their posting amounts made explicit-(like \f[CR]hledger print \-x\f[R]).-This means that any balance assignments in imported files must be-evaluated; but, imported files don\[aq]t get to see the main file\[aq]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:-.IP-.EX-$ hledger print IMPORTFILE [\-\-new] >> $LEDGER_FILE-.EE-.PP-(If you think import should leave amounts implicit like print does,-please test it and send a pull request.)-.SS Commodity display styles-Imported amounts will be formatted according to the canonical commodity-styles (declared or inferred) in the main journal file.-.SS incomestatement-(is)-.PP-This command displays an income statement, showing revenues and expenses-during one or more periods.-Amounts are shown with normal positive sign, as in conventional-financial statements.-.PP-This report shows accounts declared with the \f[CR]Revenue\f[R] or-\f[CR]Expense\f[R] type (see account types).-Or if no such accounts are declared, it shows top\-level accounts named-\f[CR]revenue\f[R] or \f[CR]income\f[R] or \f[CR]expense\f[R] (case-insensitive, plurals allowed) and their subaccounts.-.PP-Example:-.IP-.EX-$ hledger incomestatement-Income Statement 2008--                   || 2008 -===================++======- Revenues          ||      -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-- income:gifts      ||   $1 - income:salary     ||   $1 -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\--                   ||   $2 -===================++======- Expenses          ||      -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-- expenses:food     ||   $1 - expenses:supplies ||   $1 -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\--                   ||   $2 -===================++======- Net:              ||    0 -.EE-.PP-This command is a higher\-level variant of the \f[CR]balance\f[R]-command, and supports many of that command\[aq]s features, such as-multi\-period reports.-It is similar to-\f[CR]hledger balance \[aq](revenues|income)\[aq] expenses\f[R], but-with smarter account detection, and revenues/income displayed with their-sign flipped.-.PP-This command also supports the output destination and output format-options The output formats supported are \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]html\f[R], and-\f[CR]json\f[R].-.SS notes-List the unique notes that appear in transactions.-.PP-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).-.PP-Example:-.IP-.EX-$ hledger notes-Petrol-Snacks-.EE-.SS payees-List the unique payee/payer names that appear in transactions.-.PP-This command lists unique payee/payer names which have been declared-with payee directives (\-\-declared), used in transaction descriptions-(\-\-used), or both (the default).-.PP-The payee/payer is the part of the transaction description before a |-character (or if there is no |, the whole description).-.PP-You can add query arguments to select a subset of transactions.-This implies \-\-used.-.PP-Example:-.IP-.EX-$ hledger payees-Store Name-Gas Station-Person A-.EE-.SS 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.-.PP-Price amounts are always displayed with their full precision, except for-reverse prices which are limited to 8 decimal digits.-.PP-Prices can be filtered by a date:, cur: or amt: query.-.PP-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.-.SS print-Show transaction journal entries, sorted by date.-.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-date).-.PP-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.-.PP-Eg:-.IP-.EX-$ 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-.EE-.SS 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.-.PP-You can use the \f[CR]\-x\f[R]/\f[CR]\-\-explicit\f[R] 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.-\f[CR]\-x\f[R] is also implied by using any of-\f[CR]\-B\f[R],\f[CR]\-V\f[R],\f[CR]\-X\f[R],\f[CR]\-\-value\f[R].-.PP-The \f[CR]\-x\f[R]/\f[CR]\-\-explicit\f[R] 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.-.SS 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).-.PP-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.-.PP-With the \f[CR]\-\-round\f[R] (\f[I]Added in 1.32\f[R]) option,-\f[CR]print\f[R] will try increasingly hard to display decimal digits-according to the commodity display styles:-.IP \[bu] 2-\f[CR]\-\-round=none\f[R] show amounts with original precisions-(default)-.IP \[bu] 2-\f[CR]\-\-round=soft\f[R] add/remove decimal zeros in amounts (except-costs)-.IP \[bu] 2-\f[CR]\-\-round=hard\f[R] round amounts (except costs), possibly hiding-significant digits-.IP \[bu] 2-\f[CR]\-\-round=all\f[R] round all amounts and costs-.PP-\f[CR]soft\f[R] is good for non\-lossy cleanup, formatting amounts more-consistently where it\[aq]s safe to do so.-.PP-\f[CR]hard\f[R] and \f[CR]all\f[R] can cause \f[CR]print\f[R] to show-invalid unbalanced journal entries; they may be useful eg for stronger-cleanup, with manual fixups when needed.-.SS print parseability-print\[aq]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 \f[CR]expr:\f[R] queries now):-.IP-.EX-# 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-.EE-.PP-There are some situations where print\[aq]s output can become-unparseable:-.IP \[bu] 2-Value reporting affects posting amounts but not balance assertion or-balance assignment amounts, potentially causing those to fail.-.IP \[bu] 2-Auto postings can generate postings with too many missing amounts.-.IP \[bu] 2-Account aliases can generate bad account names.-.SS print, other features-With \f[CR]\-B\f[R]/\f[CR]\-\-cost\f[R], amounts with costs are shown-converted to cost.-.PP-With \f[CR]\-\-new\f[R], print shows only transactions it has not seen-on a previous run.-This uses the same deduplication system as the \f[CR]import\f[R]-command.-(See import\[aq]s docs for details.)-.PP-With \f[CR]\-m DESC\f[R]/\f[CR]\-\-match=DESC\f[R], 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.-.SS print output format-This command also supports the output destination and output format-options The output formats supported are \f[CR]txt\f[R],-\f[CR]beancount\f[R] (\f[I]Added in 1.32\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-\f[CR]sql\f[R].-.PP-The \f[CR]beancount\f[R] format tries to produce Beancount\-compatible-output, as follows:-.IP \[bu] 2-Transaction and postings with unmarked status are converted to cleared-(\f[CR]*\f[R]) status.-.IP \[bu] 2-Transactions\[aq] payee and note are backslash\-escaped and-double\-quote\-escaped and wrapped in double quotes.-.IP \[bu] 2-Transaction tags are copied to Beancount #tag format.-.IP \[bu] 2-Commodity symbols are converted to upper case, and a small number of-currency symbols like \f[CR]$\f[R] are converted to the corresponding-currency names.-.IP \[bu] 2-Account name parts are capitalised and unsupported characters are-replaced with \f[CR]\-\f[R].-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 \f[CR]\-\-alias\f[R] options to bring your accounts into-compliance.)-.IP \[bu] 2-An \f[CR]open\f[R] directive is generated for each account used, on the-earliest transaction date.-.PP-Some limitations:-.IP \[bu] 2-Balance assertions are removed.-.IP \[bu] 2-Balance assignments become missing amounts.-.IP \[bu] 2-Virtual and balanced virtual postings become regular postings.-.IP \[bu] 2-Directives are not converted.-.PP-Here\[aq]s an example of print\[aq]s CSV output:-.IP-.EX-$ hledger print \-Ocsv-\[dq]txnidx\[dq],\[dq]date\[dq],\[dq]date2\[dq],\[dq]status\[dq],\[dq]code\[dq],\[dq]description\[dq],\[dq]comment\[dq],\[dq]account\[dq],\[dq]amount\[dq],\[dq]commodity\[dq],\[dq]credit\[dq],\[dq]debit\[dq],\[dq]posting\-status\[dq],\[dq]posting\-comment\[dq]-\[dq]1\[dq],\[dq]2008/01/01\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]income\[dq],\[dq]\[dq],\[dq]assets:bank:checking\[dq],\[dq]1\[dq],\[dq]$\[dq],\[dq]\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq]-\[dq]1\[dq],\[dq]2008/01/01\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]income\[dq],\[dq]\[dq],\[dq]income:salary\[dq],\[dq]\-1\[dq],\[dq]$\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq]-\[dq]2\[dq],\[dq]2008/06/01\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]gift\[dq],\[dq]\[dq],\[dq]assets:bank:checking\[dq],\[dq]1\[dq],\[dq]$\[dq],\[dq]\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq]-\[dq]2\[dq],\[dq]2008/06/01\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]gift\[dq],\[dq]\[dq],\[dq]income:gifts\[dq],\[dq]\-1\[dq],\[dq]$\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq]-\[dq]3\[dq],\[dq]2008/06/02\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]save\[dq],\[dq]\[dq],\[dq]assets:bank:saving\[dq],\[dq]1\[dq],\[dq]$\[dq],\[dq]\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq]-\[dq]3\[dq],\[dq]2008/06/02\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]save\[dq],\[dq]\[dq],\[dq]assets:bank:checking\[dq],\[dq]\-1\[dq],\[dq]$\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq]-\[dq]4\[dq],\[dq]2008/06/03\[dq],\[dq]\[dq],\[dq]*\[dq],\[dq]\[dq],\[dq]eat & shop\[dq],\[dq]\[dq],\[dq]expenses:food\[dq],\[dq]1\[dq],\[dq]$\[dq],\[dq]\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq]-\[dq]4\[dq],\[dq]2008/06/03\[dq],\[dq]\[dq],\[dq]*\[dq],\[dq]\[dq],\[dq]eat & shop\[dq],\[dq]\[dq],\[dq]expenses:supplies\[dq],\[dq]1\[dq],\[dq]$\[dq],\[dq]\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq]-\[dq]4\[dq],\[dq]2008/06/03\[dq],\[dq]\[dq],\[dq]*\[dq],\[dq]\[dq],\[dq]eat & shop\[dq],\[dq]\[dq],\[dq]assets:cash\[dq],\[dq]\-2\[dq],\[dq]$\[dq],\[dq]2\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq]-\[dq]5\[dq],\[dq]2008/12/31\[dq],\[dq]\[dq],\[dq]*\[dq],\[dq]\[dq],\[dq]pay off\[dq],\[dq]\[dq],\[dq]liabilities:debts\[dq],\[dq]1\[dq],\[dq]$\[dq],\[dq]\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq]-\[dq]5\[dq],\[dq]2008/12/31\[dq],\[dq]\[dq],\[dq]*\[dq],\[dq]\[dq],\[dq]pay off\[dq],\[dq]\[dq],\[dq]assets:bank:checking\[dq],\[dq]\-1\[dq],\[dq]$\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq]-.EE-.IP \[bu] 2-There is one CSV record per posting, with the parent transaction\[aq]s-fields repeated.-.IP \[bu] 2-The \[dq]txnidx\[dq] (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.)-.IP \[bu] 2-The amount is separated into \[dq]commodity\[dq] (the symbol) and-\[dq]amount\[dq] (numeric quantity) fields.-.IP \[bu] 2-The numeric amount is repeated in either the \[dq]credit\[dq] or-\[dq]debit\[dq] 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.)-.SS register-(reg)-.PP-Show postings and their running total.-.PP-The register command displays matched postings, across all accounts, in-date order, with their running total or running historical balance.-(See also the \f[CR]aregister\f[R] command, which shows matched-transactions in a specific account.)-.PP-register normally shows line per posting, but note that multi\-commodity-amounts will occupy multiple lines (one line per commodity).-.PP-It is typically used with a query selecting a particular account, to see-that account\[aq]s activity:-.IP-.EX-$ 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-.EE-.PP-With \f[CR]\-\-date2\f[R], it shows and sorts by secondary date instead.-.PP-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 \f[CR]\-\-align\-all\f[R] flag.-.PP-The \f[CR]\-\-historical\f[R]/\f[CR]\-H\f[R] 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:-.IP-.EX-$ 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-.EE-.PP-The \f[CR]\-\-depth\f[R] option limits the amount of sub\-account detail-displayed.-.PP-The \f[CR]\-\-average\f[R]/\f[CR]\-A\f[R] 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 \f[CR]\-\-empty\f[R] (see below).-It is affected by \f[CR]\-\-historical\f[R].-It works best when showing just one account and one commodity.-.PP-The \f[CR]\-\-related\f[R]/\f[CR]\-r\f[R] flag shows the \f[I]other\f[R]-postings in the transactions of the postings which would normally be-shown.-.PP-The \f[CR]\-\-invert\f[R] flag negates all amounts.-For example, it can be used on an income account where amounts are-normally displayed as negative numbers.-It\[aq]s also useful to show postings on the checking account together-with the related account:-.IP-.EX-$ hledger register \-\-related \-\-invert assets:checking-.EE-.PP-With a reporting interval, register shows summary postings, one per-interval, aggregating the postings to each account:-.IP-.EX-$ hledger register \-\-monthly income-2008/01                 income:salary                          $\-1          $\-1-2008/06                 income:gifts                           $\-1          $\-2-.EE-.PP-Periods with no activity, and summary postings with a zero amount, are-not shown by default; use the \f[CR]\-\-empty\f[R]/\f[CR]\-E\f[R] flag-to see them:-.IP-.EX-$ 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-.EE-.PP-Often, you\[aq]ll want to see just one line per interval.-The \f[CR]\-\-depth\f[R] option helps with this, causing subaccounts to-be aggregated:-.IP-.EX-$ hledger register \-\-monthly assets \-\-depth 1h-2008/01                 assets                                  $1           $1-2008/06                 assets                                 $\-1            0-2008/12                 assets                                 $\-1          $\-1-.EE-.PP-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.-.PP-With \f[CR]\-m DESC\f[R]/\f[CR]\-\-match=DESC\f[R], 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.-.SS Custom register output-register uses the full terminal width by default, except on windows.-You can override this by setting the \f[CR]COLUMNS\f[R] environment-variable (not a bash shell variable) or by using the-\f[CR]\-\-width\f[R]/\f[CR]\-w\f[R] option.-.PP-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\[aq]s argument, comma\-separated: \f[CR]\-\-width W,D\f[R] .-Here\[aq]s a diagram (won\[aq]t display correctly in \-\-help):-.IP-.EX-<\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- width (W) \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\->-date (10)  description (D)       account (W\-41\-D)     amount (12)   balance (12)-DDDDDDDDDD dddddddddddddddddddd  aaaaaaaaaaaaaaaaaaa  AAAAAAAAAAAA  AAAAAAAAAAAA-.EE-.PP-and some examples:-.IP-.EX-$ hledger reg                     # use terminal width (or 80 on windows)-$ hledger reg \-w 100              # use width 100-$ COLUMNS=100 hledger reg         # set with one\-time environment variable-$ export COLUMNS=100; hledger reg # set till session end (or window resize)-$ hledger reg \-w 100,40           # set overall width 100, description width 40-$ hledger reg \-w $COLUMNS,40      # use terminal width, & description width 40-.EE-.PP-This command also supports the output destination and output format-options The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],-\f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), and \f[CR]json\f[R].-.SS rewrite-Print all transactions, rewriting the postings of matched transactions.-For now the only rewrite available is adding new postings, like print-\-\-auto.-.PP-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\[aq]s first posting amount.-.PP-Examples:-.IP-.EX-$ hledger\-rewrite.hs \[ha]income \-\-add\-posting \[aq](liabilities:tax)  *.33  ; income tax\[aq] \-\-add\-posting \[aq](reserve:gifts)  $100\[aq]-$ hledger\-rewrite.hs expenses:gifts \-\-add\-posting \[aq](reserve:gifts)  *\-1\[dq]\[aq]-$ hledger\-rewrite.hs \-f rewrites.hledger-.EE-.PP-rewrites.hledger may consist of entries like:-.IP-.EX-= \[ha]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-.EE-.PP-Note the single quotes to protect the dollar sign from bash, and the two-spaces between account and amount.-.PP-More:-.IP-.EX-$ hledger rewrite \-\- [QUERY]        \-\-add\-posting \[dq]ACCT  AMTEXPR\[dq] ...-$ hledger rewrite \-\- \[ha]income        \-\-add\-posting \[aq](liabilities:tax)  *.33\[aq]-$ hledger rewrite \-\- expenses:gifts \-\-add\-posting \[aq](budget:gifts)  *\-1\[dq]\[aq]-$ hledger rewrite \-\- \[ha]income        \-\-add\-posting \[aq](budget:foreign currency)  *0.25 JPY; diversify\[aq]-.EE-.PP-Argument for \f[CR]\-\-add\-posting\f[R] option is a usual posting of-transaction with an exception for amount specification.-More precisely, you can use \f[CR]\[aq]*\[aq]\f[R] (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\[aq]s commodity.-.SS Re\-write rules in a file-During the run this tool will execute so called \[dq]Automated-Transactions\[dq] found in any journal it process.-I.e instead of specifying this operations in command line you can put-them in a journal file.-.IP-.EX-$ rewrite\-rules.journal-.EE-.PP-Make contents look like this:-.IP-.EX-= \[ha]income-    (liabilities:tax)  *.33--= expenses:gifts-    budget:gifts  *\-1-    assets:budget  *1-.EE-.PP-Note that \f[CR]\[aq]=\[aq]\f[R] (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.-.IP-.EX-$ hledger rewrite \-\- \-f input.journal \-f rewrite\-rules.journal > rewritten\-tidy\-output.journal-.EE-.PP-This is something similar to the commands pipeline:-.IP-.EX-$ hledger rewrite \-\- \-f input.journal \[aq]\[ha]income\[aq] \-\-add\-posting \[aq](liabilities:tax)  *.33\[aq] \[rs]-  | hledger rewrite \-\- \-f \- expenses:gifts      \-\-add\-posting \[aq]budget:gifts  *\-1\[aq]       \[rs]-                                                \-\-add\-posting \[aq]assets:budget  *1\[aq]       \[rs]-  > rewritten\-tidy\-output.journal-.EE-.PP-It is important to understand that relative order of such entries in-journal is important.-You can re\-use result of previously added postings.-.SS Diff output format-To use this tool for batch modification of your journal files you may-find useful output in form of unified diff.-.IP-.EX-$ hledger rewrite \-\- \-\-diff \-f examples/sample.journal \[aq]\[ha]income\[aq] \-\-add\-posting \[aq](liabilities:tax)  *.33\[aq]-.EE-.PP-Output might look like:-.IP-.EX-\-\-\- /tmp/examples/sample.journal-+++ /tmp/examples/sample.journal-\[at]\[at] \-18,3 +18,4 \[at]\[at]- 2008/01/01 income-\-    assets:bank:checking  $1-+    assets:bank:checking            $1-     income:salary-+    (liabilities:tax)                0-\[at]\[at] \-22,3 +23,4 \[at]\[at]- 2008/06/01 gift-\-    assets:bank:checking  $1-+    assets:bank:checking            $1-     income:gifts-+    (liabilities:tax)                0-.EE-.PP-If you\[aq]ll pass this through \f[CR]patch\f[R] tool you\[aq]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 \f[CR]\-\-file\f[R] options and \f[CR]include\f[R]-directives inside of these files.-.PP-Be careful.-Whole transaction being re\-formatted in a style of output from-\f[CR]hledger print\f[R].-.PP-See also:-.PP-https://github.com/simonmichael/hledger/issues/99-.SS rewrite vs. print \-\-auto-This command predates print \-\-auto, and currently does much the same-thing, but with these differences:-.IP \[bu] 2-with multiple files, rewrite lets rules in any file affect all other-files.-print \-\-auto uses standard directive scoping; rules affect only child-files.-.IP \[bu] 2-rewrite\[aq]s query limits which transactions can be rewritten; all are-printed.-print \-\-auto\[aq]s query limits which transactions are printed.-.IP \[bu] 2-rewrite applies rules specified on command line or in the journal.-print \-\-auto applies rules specified in the journal.-.SS roi-Shows the time\-weighted (TWR) and money\-weighted (IRR) rate of return-on your investments.-.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-query to identify your profit and loss transactions with-\f[CR]\-\-pnl\f[R].-.PP-If you do not record changes in the value of your investment manually,-or do not require computation of time\-weighted return (TWR),-\f[CR]\-\-pnl\f[R] could be an empty query-(\f[CR]\-\-pnl \[dq]\[dq]\f[R] or \f[CR]\-\-pnl STR\f[R] where-\f[CR]STR\f[R] does not match any of your accounts).-.PP-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.-.PP-Price directives will be taken into account if you supply appropriate-\f[CR]\-\-cost\f[R] or \f[CR]\-\-value\f[R] flags (see VALUATION).-.PP-Note, in some cases this report can fail, for these reasons:-.IP \[bu] 2-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.-.IP \[bu] 2-Error (SearchFailed): Failed to find solution for Internal Rate of-Return (IRR).-Either search does not converge to a solution, or converges too slowly.-.PP-Examples:-.IP \[bu] 2-Using roi to compute total return of investment in stocks:-https://github.com/simonmichael/hledger/blob/master/examples/investing/roi\-unrealised.ledger-.IP \[bu] 2-Cookbook > Return on Investment: https://hledger.org/roi.html-.SS Spaces and special characters in \f[CR]\-\-inv\f[R] and \f[CR]\-\-pnl\f[R]-Note that \f[CR]\-\-inv\f[R] and \f[CR]\-\-pnl\f[R]\[aq]s argument is a-query, and queries could have several space\-separated terms (see-QUERIES).-.PP-To indicate that all search terms form single command\-line argument,-you will need to put them in quotes (see Special characters):-.IP-.EX-$ hledger roi \-\-inv \[aq]term1 term2 term3 ...\[aq]-.EE-.PP-If any query terms contain spaces themselves, you will need an extra-level of nested quoting, eg:-.IP-.EX-$ hledger roi \-\-inv=\[dq]\[aq]Assets:Test 1\[aq]\[dq] \-\-pnl=\[dq]\[aq]Equity:Unrealized Profit and Loss\[aq]\[dq]-.EE-.SS Semantics of \f[CR]\-\-inv\f[R] and \f[CR]\-\-pnl\f[R]-Query supplied to \f[CR]\-\-inv\f[R] has to match all transactions that-are related to your investment.-Transactions not matching \f[CR]\-\-inv\f[R] will be ignored.-.PP-In these transactions, ROI will conside postings that match-\f[CR]\-\-inv\f[R] to be \[dq]investment postings\[dq] and other-postings (not matching \f[CR]\-\-inv\f[R]) will be sorted into two-categories: \[dq]cash flow\[dq] and \[dq]profit and loss\[dq], as ROI-needs to know which part of the investment value is your contributions-and which is due to the return on investment.-.IP \[bu] 2-\[dq]Cash flow\[dq] is depositing or withdrawing money, buying or-selling assets, or otherwise converting between your investment-commodity and any other commodity.-Example:-.RS 2-.IP-.EX-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-.EE-.RE-.IP \[bu] 2-\[dq]Profit and loss\[dq] is change in the value of your investment:-.RS 2-.IP-.EX-2019\-06\-01 Snake Oil falls in value-  investment:snake oil  = $57-  equity:unrealized profit or loss-.EE-.RE-.PP-All non\-investment postings are assumed to be \[dq]cash flow\[dq],-unless they match \f[CR]\-\-pnl\f[R] query.-Changes in value of your investment due to \[dq]profit and loss\[dq]-postings will be considered as part of your investment return.-.PP-Example: if you use \f[CR]\-\-inv snake \-\-pnl equity:unrealized\f[R],-then postings in the example below would be classifed as:-.IP-.EX-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-.EE-.SS IRR and TWR explained-\[dq]ROI\[dq] stands for \[dq]return on investment\[dq].-Traditionally this was computed as a difference between current value of-investment and its initial value, expressed in percentage of the initial-value.-.PP-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.-.PP-Internal rate of return, or \[dq]IRR\[dq] (also called-\[dq]money\-weighted rate of return\[dq]) 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.-.PP-As mentioned before, in\-flows and out\-flows would be any cash that you-personally put in or withdraw, and for the \[dq]roi\[dq] command, these-are the postings that match the query in the\f[CR]\-\-inv\f[R] argument-and NOT match the query in the\f[CR]\-\-pnl\f[R] argument.-.PP-If you manually record changes in the value of your investment as-transactions that balance them against \[dq]profit and loss\[dq] (or-\[dq]unrealized gains\[dq]) 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.-.PP-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\[aq]t done discounted cash flow analysis before.-Implementation of IRR in hledger should produce results that match the-\f[CR]=XIRR\f[R] formula in Excel.-.PP-Second way to compute rate of return that \f[CR]roi\f[R] command-implements is called \[dq]time\-weighted rate of return\[dq] or-\[dq]TWR\[dq].-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.-.PP-TWR represents your investment as an imaginary \[dq]unit fund\[dq] where-in\-flows/ out\-flows lead to buying or selling \[dq]units\[dq] of your-investment and changes in its value change the value of \[dq]investment-unit\[dq].-Change in \[dq]unit price\[dq] 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.-.PP-References:-.IP \[bu] 2-Explanation of rate of return-.IP \[bu] 2-Explanation of IRR-.IP \[bu] 2-Explanation of TWR-.IP \[bu] 2-IRR vs TWR-.IP \[bu] 2-Examples of computing IRR and TWR and discussion of the limitations of-both metrics-.SS stats-Show journal and performance statistics.-.PP-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.-.PP-The default output is fairly impersonal, though it reveals the main file-name.-With \f[CR]\-v/\-\-verbose\f[R], more details are shown, like file-paths, included files, and commodity names.-.PP-It also shows some run time statistics:-.IP \[bu] 2-elapsed time-.IP \[bu] 2-throughput: the number of transactions processed per second-.IP \[bu] 2-live: the peak memory in use by the program to do its work-.IP \[bu] 2-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.-.PP-The \f[CR]stats\f[R] command\[aq]s run time is similar to that of a-balance report.-.PP-Example:-.IP-.EX-$ 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-.EE-.PP-This command supports the \-o/\-\-output\-file option (but not-\-O/\-\-output\-format).-.SS tags-List the tags used in the journal, or their values.-.PP-This command lists the tag names used in the journal, whether on-transactions, postings, or account declarations.-.PP-With a TAGREGEX argument, only tag names matching this regular-expression (case insensitive, infix matched) are shown.-.PP-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.-.PP-With the \-\-values flag, the tags\[aq] unique non\-empty values are-listed instead.-With \-E/\-\-empty, blank/empty values are also shown.-.PP-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.)-.PP-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.-.SS test-Run built\-in unit tests.-.PP-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.-.PP-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!-.PP-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:-.IP-.EX-$ hledger test \-\- \-pData.Amount \-\-color=never-.EE-.PP-For help on these, see https://github.com/feuerbach/tasty#options-(\f[CR]\-\- \-\-help\f[R] currently doesn\[aq]t show them).-.PP-.SH PART 5: COMMON TASKS-Here are some quick examples of how to do some basic tasks with hledger.-.SS Getting help-Here\[aq]s how to list commands and view options and command docs:-.IP-.EX-$ hledger                # show available commands-$ hledger \-\-help         # show common options-$ hledger CMD \-\-help     # show CMD\[aq]s options, common options and CMD\[aq]s documentation-.EE-.PP-You can also view your hledger version\[aq]s manual in several formats-by using the help command.-Eg:-.IP-.EX-$ 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-.EE-.PP-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.-.SS 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:-.IP \[bu] 2-command\-specific options must go after the command (it\[aq]s fine to-put common options there too: \f[CR]hledger CMD OPTS ARGS\f[R])-.IP \[bu] 2-running add\-on executables directly simplifies command line parsing-(\f[CR]hledger\-ui OPTS ARGS\f[R])-.IP \[bu] 2-enclose \[dq]problematic\[dq] args in single quotes-.IP \[bu] 2-if needed, also add a backslash to hide regular expression-metacharacters from the shell-.IP \[bu] 2-to see how a misbehaving command line is being parsed, add-\f[CR]\-\-debug=2\f[R].-.SS Starting a journal file-hledger looks for your accounting data in a journal file,-\f[CR]$HOME/.hledger.journal\f[R] by default:-.IP-.EX-$ hledger stats-The hledger journal file \[dq]/Users/simon/.hledger.journal\[dq] was not found.-Please create it first, eg with \[dq]hledger add\[dq] or a text editor.-Or, specify an existing journal file with \-f or LEDGER_FILE.-.EE-.PP-You can override this by setting the \f[CR]LEDGER_FILE\f[R] environment-variable (see below).-It\[aq]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:-.IP-.EX-$ mkdir \[ti]/finance-$ cd \[ti]/finance-$ git init-Initialized empty Git repository in /Users/simon/finance/.git/-$ touch 2023.journal-$ echo \[dq]export LEDGER_FILE=$HOME/finance/2023.journal\[dq] >> \[ti]/.profile-$ source \[ti]/.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 ()-.EE-.SS Setting LEDGER_FILE-How to set \f[CR]LEDGER_FILE\f[R] permanently depends on your setup:-.PP-On unix and mac, running these commands in the terminal will work for-many people; adapt as needed:-.IP-.EX-$ echo \[aq]export LEDGER_FILE=\[ti]/finance/2023.journal\[aq] >> \[ti]/.profile-$ source \[ti]/.profile-.EE-.PP-When correctly configured, in a new terminal window-\f[CR]env | grep LEDGER_FILE\f[R] will show your file, and so will-\f[CR]hledger files\f[R].-.PP-On mac, this additional step might be helpful for GUI applications (like-Emacs started from the dock): add an entry to-\f[CR]\[ti]/.MacOSX/environment.plist\f[R] like-.IP-.EX-{-  \[dq]LEDGER_FILE\[dq] : \[dq]\[ti]/finance/2023.journal\[dq]-}-.EE-.PP-and then run \f[CR]killall Dock\f[R] in a terminal window (or restart-the machine).-.PP-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):-.IP-.EX-> CD-> MKDIR finance-> SETX LEDGER_FILE \[dq]C:\[rs]Users\[rs]USERNAME\[rs]finance\[rs]2023.journal\[dq]-.EE-.SS 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..).-.PP-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.-.PP-Add an opening balances transaction to the journal, declaring the-balances on this date.-Here are two ways to do it:-.IP \[bu] 2-The first way: open the journal in any text editor and save an entry-like this:-.RS 2-.IP-.EX-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-.EE-.PP-These are start\-of\-day balances, ie whatever was in the account at the-end of the previous day.-.PP-The * after the date is an optional status flag.-Here it means \[dq]cleared & confirmed\[dq].-.PP-The currency symbols are optional, but usually a good idea as you\[aq]ll-be dealing with multiple currencies sooner or later.-.PP-The = amounts are optional balance assertions, providing extra error-checking.-.RE-.IP \[bu] 2-The second way: run \f[CR]hledger add\f[R] and follow the prompts to-record a similar transaction:-.RS 2-.IP-.EX-$ 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]: .-.EE-.RE-.PP-If you\[aq]re using version control, this could be a good time to commit-the journal.-Eg:-.IP-.EX-$ git commit \-m \[aq]initial balances\[aq] 2023.journal-.EE-.SS 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.-.PP-Here are some simple transactions, see the hledger_journal(5) manual and-hledger.org for more ideas:-.IP-.EX-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-.EE-.SS Reconciling-Periodically you should reconcile \- compare your hledger\-reported-balances against external sources of truth, like bank statements or your-bank\[aq]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.-.PP-A typical workflow:-.IP "1." 3-Reconcile cash.-Count what\[aq]s in your wallet.-Compare with what hledger reports (\f[CR]hledger bal cash\f[R]).-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 (\f[CR]hledger reg cash\f[R]).-If you can\[aq]t find the error, add an adjustment transaction.-Eg if you have $105 after the above, and can\[aq]t explain the missing-$2, it could be:-.RS 4-.IP-.EX-2023\-01\-16 * adjust cash-    assets:cash    $\-2 = $105-    expenses:misc-.EE-.RE-.IP "2." 3-Reconcile checking.-Log in to your bank\[aq]s website.-Compare today\[aq]s (cleared) balance with hledger\[aq]s cleared balance-(\f[CR]hledger bal checking \-C\f[R]).-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-\f[CR]hledger reg checking \-C\f[R].-This will be easier if you generally record transaction dates quite-similar to your bank\[aq]s clearing dates.-.IP "3." 3-Repeat for other asset/liability accounts.-.PP-Tip: instead of the register command, use hledger\-ui to see a-live\-updating register while you edit the journal:-\f[CR]hledger\-ui \-\-watch \-\-register checking \-C\f[R]-.PP-After reconciling, it could be a good time to mark the reconciled-transactions\[aq] status as \[dq]cleared and confirmed\[dq], if you want-to track that, by adding the \f[CR]*\f[R] marker.-Eg in the paycheck transaction above, insert \f[CR]*\f[R] between-\f[CR]2023\-01\-15\f[R] and \f[CR]paycheck\f[R]-.PP-If you\[aq]re using version control, this can be another good time to-commit:-.IP-.EX-$ git commit \-m \[aq]txns\[aq] 2023.journal-.EE-.SS Reporting-Here are some basic reports.-.PP-Show all transactions:-.IP-.EX-$ 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-.EE-.PP-Show account names, and their hierarchy:-.IP-.EX-$ hledger accounts \-\-tree-assets-  bank-    checking-    savings-  cash-equity-  opening/closing balances-expenses-  food-  misc-income-  gifts-  salary-liabilities-  creditcard-.EE-.PP-Show all account totals:-.IP-.EX-$ 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-.EE-.PP-Show only asset and liability balances, as a flat list, limited to depth-2:-.IP-.EX-$ hledger bal assets liabilities \-2-               $4000  assets:bank-                $105  assets:cash-                $\-50  liabilities:creditcard-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\--               $4055-.EE-.PP-Show the same thing without negative numbers, formatted as a simple-balance sheet:-.IP-.EX-$ 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 -.EE-.PP-The final total is your \[dq]net worth\[dq] on the end date.-(Or use \f[CR]bse\f[R] for a full balance sheet with equity.)-.PP-Show income and expense totals, formatted as an income statement:-.IP-.EX-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 -.EE-.PP-The final total is your net income during this period.-.PP-Show transactions affecting your wallet, with running total:-.IP-.EX-$ 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-.EE-.PP-Show weekly posting counts as a bar chart:-.IP-.EX-$ hledger activity \-W-2019\-12\-30 *****-2023\-01\-06 ****-2023\-01\-13 ****-.EE-.SS Migrating to a new file+.TH "HLEDGER" "1" "June 2024" "hledger-1.34 " "hledger User Manuals"++++.SH NAME+hledger \- a robust, friendly plain text accounting app (command line+version).+.SH SYNOPSIS+\f[CR]hledger\f[R]+.PD 0+.P+.PD+or+.PD 0+.P+.PD+\f[CR]hledger COMMAND [OPTS] [ARGS]\f[R]+.PD 0+.P+.PD+or+.PD 0+.P+.PD+\f[CR]hledger ADDONCMD [OPTS] \-\- [ADDONOPTS] [ADDONARGS]\f[R]+.SH DESCRIPTION+hledger is a robust, user\-friendly, cross\-platform set of programs for+tracking money, time, or any other commodity, using double\-entry+accounting and a simple, editable file format.+hledger is inspired by and largely compatible with ledger(1), and+largely interconvertible with beancount(1).+.PP+This manual is for hledger\[aq]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\[aq]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+.PD 0+.P+.PD+\f[CR]hledger \-\-man\f[R], \f[CR]hledger \-\-info\f[R] or+\f[CR]hledger help [TOPIC]\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).+Many reports are available, as subcommands.+hledger will also detect other \f[CR]hledger\-*\f[R] executables as+extra subcommands.+.PP+hledger usually reads from (and appends to) a journal file specified by+the \f[CR]LEDGER_FILE\f[R] environment variable (defaulting to+\f[CR]$HOME/.hledger.journal\f[R]); or you can specify files with+\f[CR]\-f\f[R] options.+It can also read timeclock files, timedot files, or any CSV/SSV/TSV file+with a date field.+.PP+Here is a small journal file describing one transaction:+.IP+.EX+2015\-10\-16 bought food+  expenses:food          $10+  assets:cash+.EE+.PP+Transactions are dated movements of money (etc.)+between two or more \f[I]accounts\f[R]: bank accounts, your wallet,+revenue/expense categories, people, etc.+You can choose any account names you wish, using \f[CR]:\f[R] to+indicate subaccounts.+There must be at least two spaces between account name and amount.+Positive amounts are inflow to that account (\f[I]debit\f[R]), negatives+are outflow from it (\f[I]credit\f[R]).+(Some reports show revenue, liability and equity account balances as+negative numbers as a result; this is normal.)+.PP+hledger\[cq]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).+.PP+To get started, run \f[CR]hledger add\f[R] and follow the prompts, or+save some entries like the above in \f[CR]$HOME/.hledger.journal\f[R],+then try commands like:+.IP+.EX+$ hledger print \-x+$ hledger aregister assets+$ hledger balance+$ hledger balancesheet+$ hledger incomestatement+.EE+.PP+Run \f[CR]hledger\f[R] to list the commands.+See also the \[dq]Starting a journal file\[dq] and \[dq]Setting opening+balances\[dq] sections in PART 5: COMMON TASKS.+.SH PART 1: USER INTERFACE+.SH Input+hledger reads one or more data files, each time you run it.+You can specify a file with \f[CR]\-f\f[R], like so+.IP+.EX+$ hledger \-f FILE print+.EE+.PP+Files are most often in hledger\[aq]s journal format, with the+\f[CR].journal\f[R] file extension (\f[CR].hledger\f[R] or \f[CR].j\f[R]+also work); these files describe transactions, like an accounting+general journal.+.PP+When no file is specified, hledger looks for \f[CR].hledger.journal\f[R]+in your home directory.+.PP+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\[aq]s not+required, but helps keep things fast and organised).+So we usually configure a different journal file, by setting the+\f[CR]LEDGER_FILE\f[R] environment variable, to something like+\f[CR]\[ti]/finance/2023.journal\f[R].+For more about how to do that on your system, see Common tasks > Setting+LEDGER_FILE.+.SS Text encoding+Data files containing non\-ascii characters must use UTF\-8 encoding.+An optional byte order mark (BOM) is allowed, at the beginning of the+file (only).+.PP+Also, your system should be configured with a locale that can decode+UTF\-8 text.+On some unix systems, you may need set the \f[CR]LANG\f[R] environment+variable, eg.+You can read more about this in Unicode characters, below.+.PP+On unix systems you can check a file\[aq]s encoding with the+\f[CR]file\f[R] command.+If you need to import from a UTF\-16\-encoded CSV file, say, you can+convert it to UTF\-8 with the \f[CR]iconv\f[R] command.+.SS Data formats+Usually the data file is in hledger\[aq]s journal format, but it can be+in any of the supported file formats, which currently are:+.PP+.TS+tab(@);+lw(13.5n) lw(33.0n) lw(23.5n).+T{+Reader:+T}@T{+Reads:+T}@T{+Automatically used for files with extensions:+T}+_+T{+\f[CR]journal\f[R]+T}@T{+hledger journal files and some Ledger journals, for transactions+T}@T{+\f[CR].journal\f[R] \f[CR].j\f[R] \f[CR].hledger\f[R] \f[CR].ledger\f[R]+T}+T{+\f[CR]timeclock\f[R]+T}@T{+timeclock files, for precise time logging+T}@T{+\f[CR].timeclock\f[R]+T}+T{+\f[CR]timedot\f[R]+T}@T{+timedot files, for approximate time logging+T}@T{+\f[CR].timedot\f[R]+T}+T{+\f[CR]csv\f[R]+T}@T{+Comma or other character separated values, for data import+T}@T{+\f[CR].csv\f[R]+T}+T{+\f[CR]ssv\f[R]+T}@T{+Semicolon separated values+T}@T{+\f[CR].ssv\f[R]+T}+T{+\f[CR]tsv\f[R]+T}@T{+Tab separated values+T}@T{+\f[CR].tsv\f[R]+T}+T{+\f[CR]rules\f[R]+T}@T{+CSV/SSV/TSV/other separated values, alternate way+T}@T{+\f[CR].rules\f[R]+T}+.TE+.PP+These formats are described in more detail below.+.PP+hledger detects the format automatically based on the file extensions+shown above.+If it can\[aq]t recognise the file extension, it assumes+\f[CR]journal\f[R] format.+So for non\-journal files, it\[aq]s important to use a recognised file+extension, so as to either read successfully or to show relevant error+messages.+.PP+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:+.IP+.EX+$ hledger \-f tsv:/some/file.dat stats+.EE+.SS Standard input+The file name \f[CR]\-\f[R] means standard input:+.IP+.EX+$ cat FILE | hledger \-f\- print+.EE+.PP+If reading non\-journal data in this way, you\[aq]ll need to write the+format as a prefix, like \f[CR]timeclock:\f[R] here:+.IP+.EX+$ echo \[aq]i 2009/13/1 08:00:00\[aq] | hledger print \-f timeclock:\-+.EE+.SS Multiple files+You can specify multiple \f[CR]\-f\f[R] options, to read multiple files+as one big journal.+When doing this, note that certain features (described below) will be+affected:+.IP \[bu] 2+Balance assertions will not see the effect of transactions in previous+files.+(Usually this doesn\[aq]t matter as each file will set the corresponding+opening balances.)+.IP \[bu] 2+Some directives will not affect previous or subsequent files.+.PP+If needed, you can work around these by using a single parent file which+includes the others, or concatenating the files into one, eg:+\f[CR]cat a.journal b.journal | hledger \-f\- CMD\f[R].+.SS 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:+.IP \[bu] 2+Are the input files parseable, with valid syntax ?+.IP \[bu] 2+Are all transactions balanced ?+.IP \[bu] 2+Do all balance assertions pass ?+.PP+With the \f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R] flag, additional checks+are performed:+.IP \[bu] 2+Are all accounts posted to, declared with an \f[CR]account\f[R]+directive ?+(Account error checking)+.IP \[bu] 2+Are all commodities declared with a \f[CR]commodity\f[R] directive ?+(Commodity error checking)+.IP \[bu] 2+Are all commodity conversions declared explicitly ?+.PP+You can use the check command to run individual checks \-\- the ones+listed above and some more.+.SH 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.+.PP+To show the commands list, run \f[CR]hledger\f[R] with no arguments.+The commands are described in detail in PART 4: COMMANDS, below.+.PP+To use a particular command, run+\f[CR]hledger CMD [CMDOPTS] [CMDARGS]\f[R],+.IP \[bu] 2+CMD is the full command name, or its standard abbreviation shown in the+commands list, or any unambiguous prefix of the name.+.IP \[bu] 2+CMDOPTS are command\-specific options, if any.+Command\-specific options must be written after the command name.+Eg: \f[CR]hledger print \-x\f[R].+.IP \[bu] 2+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: \f[CR]hledger reg assets:checking\f[R].+.PP+To list a command\[aq]s options, arguments, and documentation in the+terminal, run \f[CR]hledger CMD \-h\f[R].+Eg: \f[CR]hledger bal \-h\f[R].+.SS Add\-on commands+In addition to the built\-in commands, you can install \f[I]add\-on+commands\f[R]: programs or scripts named \[dq]hledger\-SOMETHING\[dq],+which will also appear in hledger\[aq]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\[aq]s bin/ directory, documented at+https://hledger.org/scripts.html.+.PP+More precisely, add\-on commands are programs or scripts in your+shell\[aq]s PATH, whose name starts with \[dq]hledger\-\[dq] and ends+with no extension or a recognised extension (\[dq].bat\[dq],+\[dq].com\[dq], \[dq].exe\[dq], \[dq].hs\[dq], \[dq].js\[dq],+\[dq].lhs\[dq], \[dq].lua\[dq], \[dq].php\[dq], \[dq].pl\[dq],+\[dq].py\[dq], \[dq].rb\[dq], \[dq].rkt\[dq], or \[dq].sh\[dq]), and (on+unix and mac) which has executable permission for the current user.+.PP+You can run add\-on commands using hledger, much like built\-in+commands:+\f[CR]hledger ADDONCMD [\-\- ADDONCMDOPTS] [ADDONCMDARGS]\f[R].+But note the double hyphen argument, required before add\-on\-specific+options.+Eg: \f[CR]hledger ui \-\- \-\-watch\f[R] or+\f[CR]hledger web \-\- \-\-serve\f[R].+If this causes difficulty, you can always run the add\-on directly,+without using \f[CR]hledger\f[R]: \f[CR]hledger\-ui \-\-watch\f[R] or+\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.+.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+                            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 (\[dq]=\[dq]) to all transactions+     \-\-forecast[=PERIOD]    Generate extra transactions from periodic rules+                            (\[dq]\[ti]\[dq]), 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\[aq]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\[aq]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:+                            \[aq]then\[aq]:     value on transaction dates+                            \[aq]end\[aq]:      value at period end(s)+                            \[aq]now\[aq]:      value today+                            YYYY\-MM\-DD: value on given date+  \-c \-\-commodity\-style=S    Override a commodity\[aq]s display style.+                            Eg: \-c \[aq].\[aq] or \-c \[aq]1.000,00 EUR\[aq]+     \-\-color=YN \-\-colour    Use ANSI color codes in text output? Can be+                            \[aq]y\[aq]/\[aq]yes\[aq]/\[aq]always\[aq], \[aq]n\[aq]/\[aq]no\[aq]/\[aq]never\[aq] or \[aq]auto\[aq].+     \-\-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+     \-\-tldr                 show command examples with tldr+     \-\-info                 show the manual with info+     \-\-man                  show the manual with man+     \-\-version              show version information+.EE+.PP+Usually hledger accepts any unambiguous flag prefix, eg you can write+\f[CR]\-\-tl\f[R] instead of \f[CR]\-\-tldr\f[R] or \f[CR]\-\-dry\f[R]+instead of \f[CR]\-\-dry\-run\f[R].+.PP+If the same option appears more than once in a command, usually the last+(right\-most) wins.+.PP+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.+.PP+Below are more tips for using the command line interface \- feel free to+skip these until you need them.+.SS Special characters+.SS Single escaping (shell metacharacters)+In shell command lines, characters significant to your shell \- such as+spaces, \f[CR]<\f[R], \f[CR]>\f[R], \f[CR](\f[R], \f[CR])\f[R],+\f[CR]|\f[R], \f[CR]$\f[R] and \f[CR]\[rs]\f[R] \- should be+\[dq]shell\-escaped\[dq] 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:+.IP+.EX+$ hledger register \[aq]credit card\[aq]+.EE+.PP+or:+.IP+.EX+$ hledger register credit\[rs] card+.EE+.PP+Windows users should keep in mind that \f[CR]cmd\f[R] treats single+quote as a regular character, so you should be using double quotes+exclusively.+PowerShell treats both single and double quotes as quotes.+.SS Double escaping (regular expression metacharacters)+Characters significant in regular expressions (described below) \- such+as \f[CR].\f[R], \f[CR]\[ha]\f[R], \f[CR]$\f[R], \f[CR][\f[R],+\f[CR]]\f[R], \f[CR](\f[R], \f[CR])\f[R], \f[CR]|\f[R], and+\f[CR]\[rs]\f[R] \- may need to be \[dq]regex\-escaped\[dq] if you+don\[aq]t want them to be interpreted by hledger\[aq]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 \f[CR]$\f[R] sign while using the bash shell:+.IP+.EX+$ hledger balance cur:\[aq]\[rs]$\[aq]+.EE+.PP+or:+.IP+.EX+$ hledger balance cur:\[rs]\[rs]$+.EE+.SS 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 \f[CR]$\f[R] sign while using the bash shell and+running an add\-on command (\f[CR]ui\f[R]):+.IP+.EX+$ hledger ui cur:\[aq]\[rs]\[rs]$\[aq]+.EE+.PP+or:+.IP+.EX+$ hledger ui cur:\[rs]\[rs]\[rs]\[rs]$+.EE+.PP+If you wondered why \f[I]four\f[R] backslashes, perhaps this helps:+.PP+.TS+tab(@);+l l.+T{+unescaped:+T}@T{+\f[CR]$\f[R]+T}+T{+escaped:+T}@T{+\f[CR]\[rs]$\f[R]+T}+T{+double\-escaped:+T}@T{+\f[CR]\[rs]\[rs]$\f[R]+T}+T{+triple\-escaped:+T}@T{+\f[CR]\[rs]\[rs]\[rs]\[rs]$\f[R]+T}+.TE+.PP+Or, you can avoid the extra escaping by running the add\-on executable+directly:+.IP+.EX+$ hledger\-ui cur:\[rs]\[rs]$+.EE+.SS 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:+.IP \[bu] 2+an \[at]argumentfile+.IP \[bu] 2+hledger\-ui\[aq]s filter field+.IP \[bu] 2+hledger\-web\[aq]s search form+.IP \[bu] 2+GHCI\[aq]s prompt (used by developers).+.SS Unicode characters+hledger is expected to handle non\-ascii characters correctly:+.IP \[bu] 2+they should be parsed correctly in input files and on the command line,+by all hledger tools (add, iadd, hledger\-web\[aq]s search/add/edit+forms, etc.)+.IP \[bu] 2+they should be displayed correctly by all hledger tools, and on\-screen+alignment should be preserved.+.PP+This requires a well\-configured environment.+Here are some tips:+.IP \[bu] 2+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:+\f[CR]export LANG=en_US.UTF\-8\f[R].+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).+.IP \[bu] 2+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.+.IP \[bu] 2+The terminal must be using a font which includes the required unicode+glyphs.+.IP \[bu] 2+The terminal should be configured to display wide characters as double+width (for report alignment).+.IP \[bu] 2+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).+.SS Regular expressions+A regular expression (regexp) is a small piece of text where certain+characters (like \f[CR].\f[R], \f[CR]\[ha]\f[R], \f[CR]$\f[R],+\f[CR]+\f[R], \f[CR]*\f[R], \f[CR]()\f[R], \f[CR]|\f[R], \f[CR][]\f[R],+\f[CR]\[rs]\f[R]) 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.+.PP+hledger supports regexps whenever you are entering a pattern to match+something, eg in query arguments, account aliases, CSV if rules,+hledger\-web\[aq]s search form, hledger\-ui\[aq]s \f[CR]/\f[R] search,+etc.+You may need to wrap them in quotes, especially at the command line (see+Special characters above).+Here are some examples:+.PP+Account name queries (quoted for command line use):+.IP+.EX+Regular expression:  Matches:+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+bank                 assets:bank, assets:bank:savings, expenses:art:banksy, ...+:bank                assets:bank:savings, expenses:art:banksy+:bank:               assets:bank:savings+\[aq]\[ha]bank\[aq]              none of those ( \[ha] matches beginning of text )+\[aq]bank$\[aq]              assets:bank   ( $ matches end of text )+\[aq]big \[rs]$ bank\[aq]        big $ bank    ( \[rs] disables following character\[aq]s special meaning )+\[aq]\[rs]bbank\[rs]b\[aq]           assets:bank, assets:bank:savings  ( \[rs]b matches word boundaries )+\[aq](sav|check)ing\[aq]     saving or checking  ( (|) matches either alternative )+\[aq]saving|checking\[aq]    saving or checking  ( outer parentheses are not needed )+\[aq]savings?\[aq]           saving or savings   ( ? matches 0 or 1 of the preceding thing )+\[aq]my +bank\[aq]           my bank, my  bank, ... ( + matches 1 or more of the preceding thing )+\[aq]my *bank\[aq]           mybank, my bank, my  bank, ... ( * matches 0 or more of the preceding thing )+\[aq]b.nk\[aq]               bank, bonk, b nk, ... ( . matches any character )+.EE+.PP+Some other queries:+.IP+.EX+desc:\[aq]amazon|amzn|audible\[aq]  Amazon transactions+cur:EUR              amounts with commodity symbol containing EUR+cur:\[aq]\[rs]$\[aq]             amounts with commodity symbol containing $+cur:\[aq]\[ha]\[rs]$$\[aq]           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+.EE+.PP+Account name aliases: accept \f[CR].\f[R] instead of \f[CR]:\f[R] as+account separator:+.IP+.EX+alias /\[rs]./=:         replaces all periods in account names with colons+.EE+.PP+Show multiple top\-level accounts combined as one:+.IP+.EX+\-\-alias=\[aq]/\[ha][\[ha]:]+/=combined\[aq]  ( [\[ha]:] matches any character other than : )+.EE+.PP+Show accounts with the second\-level part removed:+.IP+.EX+\-\-alias \[aq]/\[ha]([\[ha]:]+):[\[ha]:]+/ = \[rs]1\[aq]+                     match a top\-level account and a second\-level account+                     and replace those with just the top\-level account+                     ( \[rs]1 in the replacement text means \[dq]whatever was matched+                     by the first parenthesised part of the regexp\[dq]+.EE+.PP+CSV rules: match CSV records containing dining\-related MCC codes:+.IP+.EX+if \[rs]?MCC581[124]+.EE+.PP+Match CSV records with a specific amount around the end/start of month:+.IP+.EX+if %amount \[rs]b3\[rs].99+&  %date   (29|30|31|01|02|03)$+.EE+.SS hledger\[aq]s regular expressions+hledger\[aq]s regular expressions come from the regex\-tdfa library.+If they\[aq]re not doing what you expect, it\[aq]s important to know+exactly what they support:+.IP "1." 3+they are case insensitive+.IP "2." 3+they are infix matching (they do not need to match the entire thing+being matched)+.IP "3." 3+they are POSIX ERE (extended regular expressions)+.IP "4." 3+they also support GNU word boundaries (\f[CR]\[rs]b\f[R],+\f[CR]\[rs]B\f[R], \f[CR]\[rs]<\f[R], \f[CR]\[rs]>\f[R])+.IP "5." 3+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 \f[CR]\[rs]1\f[R], it will match the digit+\f[CR]1\f[R].+.IP "6." 3+they do not support mode modifiers (\f[CR](?s)\f[R]), character classes+(\f[CR]\[rs]w\f[R], \f[CR]\[rs]d\f[R]), or anything else not mentioned+above.+.PP+Some things to note:+.IP \[bu] 2+In the \f[CR]alias\f[R] directive and \f[CR]\-\-alias\f[R] option,+regular expressions must be enclosed in forward slashes+(\f[CR]/REGEX/\f[R]).+Elsewhere in hledger, these are not required.+.IP \[bu] 2+In queries, to match a regular expression metacharacter like+\f[CR]$\f[R] as a literal character, prepend a backslash.+Eg to search for amounts with the dollar sign in hledger\-web, write+\f[CR]cur:\[rs]$\f[R].+.IP \[bu] 2+On the command line, some metacharacters like \f[CR]$\f[R] have a+special meaning to the shell and so must be escaped at least once more.+See Special characters.+.SS Argument files+You can save a set of command line options and arguments in a file, and+then reuse them by writing \f[CR]\[at]FILENAME\f[R] as a command line+argument.+Eg: \f[CR]hledger bal \[at]foo.args\f[R].+.PP+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.+For the special characters mentioned above, use one less level of+quoting than you would at the command prompt.+.SH Output+.SS 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:+.IP+.EX+$ hledger print > foo.txt+.EE+.PP+Some commands (print, register, stats, the balance commands) also+provide the \f[CR]\-o/\-\-output\-file\f[R] option, which does the same+thing without needing the shell.+Eg:+.IP+.EX+$ hledger print \-o foo.txt+$ hledger print \-o \-        # write to stdout (the default)+.EE+.SS Output format+Some commands offer other kinds of output, not just text on the+terminal.+Here are those commands and the formats currently supported:+.PP+.TS+tab(@);+lw(16.1n) lw(14.5n) lw(14.5n) lw(16.1n) lw(4.8n) lw(4.0n).+T{+\-+T}@T{+txt+T}@T{+csv/tsv+T}@T{+html+T}@T{+json+T}@T{+sql+T}+_+T{+aregister+T}@T{+Y+T}@T{+Y+T}@T{+Y+T}@T{+Y+T}@T{+T}+T{+balance+T}@T{+Y \f[I]1\f[R]+T}@T{+Y \f[I]1\f[R]+T}@T{+Y \f[I]1,2\f[R]+T}@T{+Y+T}@T{+T}+T{+balancesheet+T}@T{+Y \f[I]1\f[R]+T}@T{+Y \f[I]1\f[R]+T}@T{+Y \f[I]1\f[R]+T}@T{+Y+T}@T{+T}+T{+balancesheetequity+T}@T{+Y \f[I]1\f[R]+T}@T{+Y \f[I]1\f[R]+T}@T{+Y \f[I]1\f[R]+T}@T{+Y+T}@T{+T}+T{+cashflow+T}@T{+Y \f[I]1\f[R]+T}@T{+Y \f[I]1\f[R]+T}@T{+Y \f[I]1\f[R]+T}@T{+Y+T}@T{+T}+T{+incomestatement+T}@T{+Y \f[I]1\f[R]+T}@T{+Y \f[I]1\f[R]+T}@T{+Y \f[I]1\f[R]+T}@T{+Y+T}@T{+T}+T{+print+T}@T{+Y+T}@T{+Y+T}@T{+T}@T{+Y+T}@T{+Y+T}+T{+register+T}@T{+Y+T}@T{+Y+T}@T{+T}@T{+Y+T}@T{+T}+.TE+.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:+.IP+.EX+$ hledger print \-O csv    # print CSV on stdout+.EE+.PP+or by the filename extension of an output file specified with the+\f[CR]\-o/\-\-output\-file=FILE.FMT\f[R] option:+.IP+.EX+$ hledger balancesheet \-o foo.csv    # write CSV to foo.csv+.EE+.PP+The \f[CR]\-O\f[R] option can be combined with \f[CR]\-o\f[R] to+override the file extension, if needed:+.IP+.EX+$ hledger balancesheet \-o foo.txt \-O csv    # write CSV to foo.txt+.EE+.PP+Some notes about the various output formats:+.SS CSV output+.IP \[bu] 2+In CSV output, digit group marks (such as thousands separators) are+disabled automatically.+.SS HTML output+.IP \[bu] 2+HTML output can be styled by an optional \f[CR]hledger.css\f[R] file in+the same directory.+.SS JSON output+.IP \[bu] 2+This is not yet much used; real\-world feedback is welcome.+.IP \[bu] 2+Our JSON is rather large and verbose, since it is a faithful+representation of hledger\[aq]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\[aq]s OpenAPI specification may also be relevant.+.IP \[bu] 2+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\[aq]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)+.SS SQL output+.IP \[bu] 2+This is not yet much used; real\-world feedback is welcome.+.IP \[bu] 2+SQL output is expected to work at least with SQLite, MySQL and Postgres.+.IP \[bu] 2+For SQLite, it will be more useful if you modify the generated+\f[CR]id\f[R] field to be a PRIMARY KEY.+Eg:+.RS 2+.IP+.EX+$ hledger print \-O sql | sed \[aq]s/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g\[aq] | ...+.EE+.RE+.IP \[bu] 2+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+\f[CR]delete\f[R] or \f[CR]truncate\f[R] SQL statements) or drop tables+completely as otherwise your postings will be duped.+.SS Commodity styles+When displaying amounts, hledger infers a standard display style for+each commodity/currency, as described below in Commodity display style.+.PP+If needed, this can be overridden by a+\f[CR]\-c/\-\-commodity\-style\f[R] option (except for cost amounts and+amounts displayed by the \f[CR]print\f[R] command, which are always+displayed with all decimal digits).+For example, the following will force dollar amounts to be displayed as+shown:+.IP+.EX+$ hledger print \-c \[aq]$1.000,0\[aq]+.EE+.PP+This option can repeated to set the display style for multiple+commodities/currencies.+Its argument is as described in the commodity directive.+.PP+In some cases hledger will adjust number formatting to improve their+parseability (such as adding trailing decimal marks when needed).+.SS Colour+In terminal output, some commands can produce colour when the terminal+supports it:+.IP \[bu] 2+if the \f[CR]\-\-color/\-\-colour\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]), colour will (or will not) be used;+.IP \[bu] 2+otherwise, if the \f[CR]NO_COLOR\f[R] environment variable is set,+colour will not be used;+.IP \[bu] 2+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.+.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+\f[CR]less\f[R], or \f[CR]more\f[R].+(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,+.IP \[bu] 2+when listing commands, with \f[CR]hledger\f[R]+.IP \[bu] 2+when showing help with \f[CR]hledger [CMD] \-\-help\f[R],+.IP \[bu] 2+when viewing manuals with \f[CR]hledger help\f[R] or+\f[CR]hledger \-\-man\f[R].+.PP+Note the pager is expected to handle ANSI codes, which hledger uses eg+for bold emphasis.+For the common pager \f[CR]less\f[R] (and its \f[CR]more\f[R]+compatibility mode), we add \f[CR]R\f[R] to the \f[CR]LESS\f[R] and+\f[CR]MORE\f[R] 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 \f[CR]NO_COLOR\f[R] environment variable to 1+to disable all ANSI output (see Colour).+.SS Debug output+We intend hledger to be relatively easy to troubleshoot, introspect and+develop.+You can add \f[CR]\-\-debug[=N]\f[R] 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+\f[CR]\-o/\-\-output\-file\f[R] (unless you redirect stderr to stdout,+eg: \f[CR]2>&1\f[R]).+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:+.IP+.EX+hledger bal \-\-debug=3 2>hledger.log+.EE+.SH Environment+These environment variables affect hledger:+.PP+\f[B]COLUMNS\f[R] This is normally set by your terminal; some hledger+commands (\f[CR]register\f[R]) will format their output to this width.+If not set, they will try to use the available terminal width.+.PP+\f[B]LEDGER_FILE\f[R] The main journal file to use when not specified+with \f[CR]\-f/\-\-file\f[R].+Default: \f[CR]$HOME/.hledger.journal\f[R].+.PP+\f[B]NO_COLOR\f[R] 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+\f[CR]\-\-color=y\f[R]/\f[CR]\-\-colour=y\f[R] option.+.SH PART 2: DATA FORMATS+.SH Journal+hledger\[aq]s usual data source is a plain text file containing journal+entries in hledger \f[CR]journal\f[R] format.+If you\[aq]re looking for a quick reference, jump ahead to the journal+cheatsheet (or use the table of contents at+https://hledger.org/hledger.html).+.PP+This file represents an accounting General Journal.+The \f[CR].journal\f[R] 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.+.PP+hledger\[aq]s journal format is compatible with most of Ledger\[aq]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.+.PP+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.+.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,+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.+.PP+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\[aq]s data model.+Here\[aq]s a quick cheatsheet/overview, followed by detailed+descriptions of each part.+.SS Journal cheatsheet+.IP+.EX+# Here is the main syntax of hledger\[aq]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 \[dq]comment\[dq] / \[dq]end comment\[dq].+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\[aq]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 \[dq]type\[dq] 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\[aq]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 \[dq]periodic transaction\[dq], for budget/forecast reports+\[ti] 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\[aq]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\[aq]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\[aq]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 \[dq]pending\[dq] or \[dq]cleared\[dq].+    ; There can be a parenthesised (code) after the date/status.+                                    ; Amounts\[aq] 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\[aq]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 \[dq]Chocolate Frogs\[dq]  ; Complex commodity symbols+    assets:pouch             3 \[dq]Chocolate Frogs\[dq]  ; 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 \[at] $1.50  ; \[at]  means per\-unit cost+    assets:investments:2024\-01\-15\-02  3.0 AAAA \[at]\[at] $4    ; \[at]\[at] means total cost+                      ; \[ha] 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 \[dq]Chocolate Frogs\[dq] =      3 \[dq]Chocolate Frogs\[dq]+    assets:investments:2024\-01\-15      0.0 AAAA            =      2.0 AAAA \[at]  $1.50+    assets:investments:2024\-01\-15\-02   0.0 AAAA            =      3.0 AAAA \[at]\[at] $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+.EE+.SS Comments+Lines in the journal will be ignored if they begin with a hash+(\f[CR]#\f[R]) or a semicolon (\f[CR];\f[R]).+(See also Other syntax.)+hledger will also ignore regions beginning with a \f[CR]comment\f[R]+line and ending with an \f[CR]end comment\f[R] line (or file end).+Here\[aq]s a suggestion for choosing between them:+.IP \[bu] 2+\f[CR]#\f[R] for top\-level notes+.IP \[bu] 2+\f[CR];\f[R] for commenting out things temporarily+.IP \[bu] 2+\f[CR]comment\f[R] for quickly commenting large regions (remember+it\[aq]s there, or you might get confused)+.PP+Eg:+.IP+.EX+# a comment line+; another commentline+comment+A multi\-line comment block,+continuing until \[dq]end comment\[dq] directive+or the end of the current file.+end comment+.EE+.PP+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.+.SS 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.+.PP+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:+.IP \[bu] 2+a status character (empty, \f[CR]!\f[R], or \f[CR]*\f[R])+.IP \[bu] 2+a code (any short number or text, enclosed in parentheses)+.IP \[bu] 2+a description (any remaining text until end of line or a semicolon)+.IP \[bu] 2+a comment (any remaining text following a semicolon until end of line,+and any following indented lines beginning with a semicolon)+.IP \[bu] 2+0 or more indented \f[I]posting\f[R] lines, describing what was+transferred and the accounts involved (indented comment lines are also+allowed, but not blank lines or non\-indented lines).+.PP+Here\[aq]s a simple journal file containing one transaction:+.IP+.EX+2008/01/01 income+  assets:bank:checking   $1+  income:salary         $\-1+.EE+.SS Dates+.SS Simple dates+Dates in the journal file use \f[I]simple dates\f[R] format:+\f[CR]YYYY\-MM\-DD\f[R] or \f[CR]YYYY/MM/DD\f[R] or+\f[CR]YYYY.MM.DD\f[R], 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+\f[CR]Y\f[R] directive, or the current date when the command is run.+Some examples: \f[CR]2010\-01\-31\f[R], \f[CR]2010/01/31\f[R],+\f[CR]2010.1.31\f[R], \f[CR]1/31\f[R].+.PP+(The UI also accepts simple dates, as well as the more flexible smart+dates documented in the hledger manual.)+.SS 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 \f[CR]date:DATE\f[R].+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:+.IP+.EX+2015/5/30+    expenses:food     $10  ; food purchased on saturday 5/30+    assets:checking        ; bank cleared it on monday, date:6/1+.EE+.IP+.EX+$ hledger \-f t.j register food+2015\-05\-30                      expenses:food                  $10           $10+.EE+.IP+.EX+$ hledger \-f t.j register checking+2015\-06\-01                      assets:checking               $\-10          $\-10+.EE+.PP+DATE should be a simple date; if the year is not specified it will use+the year of the transaction\[aq]s date.+.PD 0+.P+.PD+The \f[CR]date:\f[R] tag must have a valid simple date value if it is+present, eg a \f[CR]date:\f[R] tag with no value is not allowed.+.SS 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:+.PP+.TS+tab(@);+l l.+T{+mark \ +T}@T{+status+T}+_+T{+\ +T}@T{+unmarked+T}+T{+\f[CR]!\f[R]+T}@T{+pending+T}+T{+\f[CR]*\f[R]+T}@T{+cleared+T}+.TE+.PP+When reporting, you can filter by status with the+\f[CR]\-U/\-\-unmarked\f[R], \f[CR]\-P/\-\-pending\f[R], and+\f[CR]\-C/\-\-cleared\f[R] flags (and you can combine these, eg+\f[CR]\-UP\f[R] to match all except cleared things).+Or you can use the \f[CR]status:\f[R], \f[CR]status:!\f[R], and+\f[CR]status:*\f[R] queries, or the U, P, C keys in hledger\-ui.+.PP+(Note: in Ledger the \[dq]unmarked\[dq] state is called+\[dq]uncleared\[dq]; in hledger we renamed it to \[dq]unmarked\[dq] for+semantic clarity.)+.PP+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.+.PP+What \[dq]uncleared\[dq], \[dq]pending\[dq], and \[dq]cleared\[dq]+actually mean is up to you.+Here\[aq]s one suggestion:+.PP+.TS+tab(@);+lw(9.7n) lw(60.3n).+T{+status+T}@T{+meaning+T}+_+T{+uncleared+T}@T{+recorded but not yet reconciled; needs review+T}+T{+pending+T}@T{+tentatively reconciled (if needed, eg during a big reconciliation)+T}+T{+cleared+T}@T{+complete, reconciled as far as possible, and considered correct+T}+.TE+.PP+With this scheme, you would use \f[CR]\-PC\f[R] to see the current+balance at your bank, \f[CR]\-U\f[R] 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.+.SS Code+After the status mark, but before the description, you can optionally+write a transaction \[dq]code\[dq], enclosed in parentheses.+This is a good place to record a check number, or some other important+transaction id or reference number.+.SS Description+After the date, status mark and/or code fields, the rest of the line (or+until a comment is begun with \f[CR];\f[R]) is the transaction\[aq]s+description.+Here you can describe the transaction (called the \[dq]narration\[dq] in+traditional bookkeeping), or you can record a payee/payer name, or you+can leave it empty.+.PP+Transaction descriptions show up in print output and in register+reports, and can be listed with the descriptions command.+.PP+You can query by description with \f[CR]desc:DESCREGEX\f[R], or pivot on+description with \f[CR]\-\-pivot desc\f[R].+.SS 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 \f[CR]|\f[R] (pipe) character in the+description.+This divides it into a \[dq]payee\[dq] field on the left, and a+\[dq]note\[dq] field on the right.+(Either can be empty.)+.PP+You can query these with \f[CR]payee:PAYEEREGEX\f[R] and+\f[CR]note:NOTEREGEX\f[R], list their values with the payees and notes+commands, or pivot on \f[CR]payee\f[R] or \f[CR]note\f[R].+.PP+Note: in transactions with no \f[CR]|\f[R] character, description,+payee, and note all have the same value.+Once a \f[CR]|\f[R] is added, they become distinct.+(If you\[aq]d like to change this behaviour, please propose it on the+mail list.)+.PP+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\[aq]ll need to ensure every+transaction description contains a \f[CR]|\f[R] and therefore a+checkable payee name, even if it\[aq]s empty.)+.SS Transaction comments+Text following \f[CR];\f[R], after a transaction description, and/or on+indented lines immediately below it, form comments for that transaction.+They are reproduced by \f[CR]print\f[R] but otherwise ignored, except+they may contain tags, which are not ignored.+.IP+.EX+2012\-01\-01 something  ; a transaction comment+    ; a second line of transaction comment+    expenses   1+    assets+.EE+.SS 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:+.IP \[bu] 2+(optional) a status character (empty, \f[CR]!\f[R], or \f[CR]*\f[R]),+followed by a space+.IP \[bu] 2+(required) an account name (any text, optionally containing \f[B]single+spaces\f[R], until end of line or a double space)+.IP \[bu] 2+(optional) \f[B]two or more spaces\f[R] (or tabs) followed by an amount.+.PP+If the amount is positive, it is being added to the account; if+negative, it is being removed from the account.+.PP+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 \[dq]sum up to+zero\[dq] in Transaction balancing below.)+.PP+As a convenience, you can optionally leave one amount blank; hledger+will infer what it should be so as to balance the transaction.+.SS 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.+.PP+You don\[aq]t need to remember that, but if you would like to \- eg for+helping newcomers or for talking with your accountant \- here\[aq]s a+handy mnemonic:+.PP+\f[I]\f[CI]debit  / plus  / left  / short  words\f[I]\f[R]+.PD 0+.P+.PD+\f[I]\f[CI]credit / minus / right / longer words\f[I]\f[R]+.SS 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 \f[B]two or more+spaces\f[R] (or tabs).+It\[aq]s easy to forget at first.+If you ever see the amount being treated as part of the account name,+you\[aq]ll know you probably need to add another space between them.+.SS 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 \[dq]money+borrowed from Frank\[dq] or \[dq]money spent on electricity\[dq].+.PP+You can use any account names you like, but we usually start with the+traditional accounting categories, which in english are+\f[CR]assets\f[R], \f[CR]liabilities\f[R], \f[CR]equity\f[R],+\f[CR]revenues\f[R], \f[CR]expenses\f[R].+(You might see these referred to as A, L, E, R, X for short.)+.PP+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 \f[CR]assets:bank:checking\f[R] and+\f[CR]expenses:food\f[R], hledger will infer this hierarchy of five+accounts:+.IP+.EX+assets+assets:bank+assets:bank:checking+expenses+expenses:food+.EE+.PP+Shown as an outline, the hierarchical tree structure is more clear:+.IP+.EX+assets+ bank+  checking+expenses+ food+.EE+.PP+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.+.PP+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 \f[B]two or more spaces\f[R] (or tabs).+.PP+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.+.PP+Account names can be altered temporarily or permanently by account+aliases.+.SS Amounts+After the account name, there is usually an amount.+(Remember: between account name and amount, there must be two or more+spaces.)+.PP+hledger\[aq]s amount format is flexible, supporting several+international formats.+Here are some examples.+Amounts have a number (the \[dq]quantity\[dq]):+.IP+.EX+1+.EE+.PP+\&..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:+.IP+.EX+$1+4000 AAPL+3 \[dq]green apples\[dq]+.EE+.PP+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:+.IP+.EX+\-$1+$\-1+.EE+.PP+One or more spaces between the sign and the number are acceptable when+parsing (but they won\[aq]t be displayed in output):+.IP+.EX++ $1+$\-      1+.EE+.PP+Scientific E notation is allowed:+.IP+.EX+1E\-6+EUR 1E3+.EE+.PP+.SS Decimal marks+A \f[I]decimal mark\f[R] can be written as a period or a comma:+.IP+.EX+1.23+1,23+.EE+.PP+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 \f[CR]1,000\f[R] or+\f[CR]1.000\f[R] 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.+.PP+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 \f[CR]decimal\-mark\f[R] directive at the top+of each data file, like this:+.IP+.EX+decimal\-mark .+.EE+.PP+Or you can declare it per commodity with \f[CR]commodity\f[R]+directives, described below.+.PP+hledger also accepts numbers like \f[CR]10.\f[R] with no digits after+the decimal mark (and will sometimes display numbers that way to+disambiguate them \- see Trailing decimal marks).+.SS 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 \f[I]digit group+mark\f[R] \- 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:+.IP+.EX+     $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+.EE+.SS Commodity+Amounts in hledger have both a \[dq]quantity\[dq], which is a signed+decimal number, and a \[dq]commodity\[dq], which is a currency symbol,+stock ticker, or any word or phrase describing something you are+tracking.+.PP+If the commodity name contains non\-letters (spaces, numbers, or+punctuation), you must always write it inside double quotes+(\f[CR]\[dq]green apples\[dq]\f[R], \f[CR]\[dq]ABC123\[dq]\f[R]).+.PP+If you write just a bare number, that too will have a commodity, with+name \f[CR]\[dq]\[dq]\f[R]; we call that the \[dq]no\-symbol+commodity\[dq].+.PP+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:+\f[CR]1 USD, 2 EUR, 3.456 TSLA\f[R].+In practice, you will only see multi\-commodity amounts in hledger\[aq]s+output; you can\[aq]t write them directly in the journal file.+\+.PP+By default, the format of amounts in the journal influences how hledger+displays them in output.+This is explained in Commodity display style below.+.PP+.SS Costs+After a posting amount, you can note its cost (when buying) or selling+price (when selling) in another commodity, by writing either+\f[CR]\[at] UNITPRICE\f[R] or \f[CR]\[at]\[at] TOTALPRICE\f[R] after it.+This indicates a conversion transaction, where one commodity is+exchanged for another.+.PP+(You might also see this called \[dq]transaction price\[dq] 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 \[dq]cost\[dq], with the understanding that the transaction+could be a purchase or a sale.)+.PP+Costs are usually written explicitly with \f[CR]\[at]\f[R] or+\f[CR]\[at]\[at]\f[R], 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.+.PP+As an example, here are several ways to record purchases of a foreign+currency in hledger, using the cost notation either explicitly or+implicitly:+.IP "1." 3+Write the price per unit, as \f[CR]\[at] UNITPRICE\f[R] after the+amount:+.RS 4+.IP+.EX+2009/1/1+  assets:euros     €100 \[at] $1.35  ; one hundred euros purchased at $1.35 each+  assets:dollars                 ; balancing amount is \-$135.00+.EE+.RE+.IP "2." 3+Write the total price, as \f[CR]\[at]\[at] TOTALPRICE\f[R] after the+amount:+.RS 4+.IP+.EX+2009/1/1+  assets:euros     €100 \[at]\[at] $135  ; one hundred euros purchased at $135 for the lot+  assets:dollars+.EE+.RE+.IP "3." 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 \f[CR]€100 \[at]\[at] $135\f[R], as in example 2:+.RS 4+.IP+.EX+2009/1/1+  assets:euros     €100          ; one hundred euros purchased+  assets:dollars  $\-135          ; for $135+.EE+.RE+.PP+Amounts can be converted to cost at report time using the+\f[CR]\-B/\-\-cost\f[R] flag; this is discussed more in the Cost+reporting section.+.PP+Note that the cost normally should be a positive amount, though it\[aq]s+not required to be.+This can be a little confusing, see discussion at+\-\-infer\-market\-prices: market prices from transactions.+.SS Balance assertions+hledger supports Ledger\-style balance assertions in journal files.+These look like, for example, \f[CR]= EXPECTEDBALANCE\f[R] following a+posting\[aq]s amount.+Eg here we assert the expected dollar balance in accounts a and b after+each posting:+.IP+.EX+2013/1/1+  a   $1 =  $1+  b      = $\-1++2013/1/2+  a   $1 =  $2+  b  $\-1 = $\-2+.EE+.PP+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+\f[CR]\-I/\-\-ignore\-assertions\f[R] flag, which can be useful for+troubleshooting or for reading Ledger files.+(Note: this flag currently does not disable balance assignments,+described below).+.SS Assertions and ordering+hledger calculates and checks an account\[aq]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.+.PP+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.+.SS Assertions and multiple included files+Multiple files included with the \f[CR]include\f[R] 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.+.PP+And if you have multiple postings to an account on the same day, split+across multiple files, and you want to assert the account\[aq]s balance+on that day, you\[aq]ll need to put the assertion in the right file \-+the last one in the sequence, probably.+.SS Assertions and multiple \-f files+Unlike \f[CR]include\f[R], when multiple files are specified on the+command line with multiple \f[CR]\-f/\-\-file\f[R] 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.+.PP+If you do want assertions to see balance from earlier files, use+\f[CR]include\f[R], or concatenate the files temporarily.+.SS Assertions and costs+Balance assertions ignore costs, and should normally be written without+one:+.IP+.EX+2019/1/1+  (a)     $1 \[at] €1 = $1+.EE+.PP+We do allow costs to be written in balance assertion amounts, however,+and print shows them, but they don\[aq]t affect whether the assertion+passes or fails.+This is for backward compatibility (hledger\[aq]s close command used to+generate balance assertions with costs), and because balance+\f[I]assignments\f[R] do use costs (see below).+.SS Assertions and commodities+The balance assertions described so far are \[dq]\f[B]single commodity+balance assertions\f[R]\[dq]: 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.+.PP+If an account contains multiple commodities, you can assert their+balances by writing multiple postings with balance assertions, one for+each commodity:+.IP+.EX+2013/1/1+  usd   $\-1+  eur   €\-1+  both++2013/1/2+  both    0 = $1+  both    0 = €1+.EE+.PP+In hledger you can make a stronger \[dq]\f[B]sole commodity balance+assertion\f[R]\[dq] by writing two equals signs+(\f[CR]== EXPECTEDBALANCE\f[R]).+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):+.IP+.EX+2013/1/1+  usd   $\-1  == $\-1  ; these sole commodity assertions succeed+  eur   €\-1  == €\-1+  both      ;==  $1  ; this one would fail because \[aq]both\[aq] contains $ and €+.EE+.PP+It\[aq]s less easy to make a \[dq]\f[B]sole commodities balance+assertion\f[R]\[dq] (note the plural) \- ie, asserting that an account+contains two or more specified commodities and no others.+It can be done by+.IP "1." 3+isolating each commodity in a subaccount, and asserting those+.IP "2." 3+and also asserting there are no commodities in the parent account+itself:+.IP+.EX+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+.EE+.SS Assertions and subaccounts+All of the balance assertions above (both \f[CR]=\f[R] and+\f[CR]==\f[R]) are \[dq]\f[B]subaccount\-exclusive balance+assertions\f[R]\[dq]; they ignore any balances that exist in deeper+subaccounts.+.PP+In hledger you can make \[dq]\f[B]subaccount\-inclusive balance+assertions\f[R]\[dq] by adding a star after the equals (\f[CR]=*\f[R] or+\f[CR]==*\f[R]):+.IP+.EX+2019/1/1+  equity:start+  assets:checking  $10+  assets:savings   $10+  assets            $0 ==* $20  ; assets + subaccounts contains $20 and nothing else+.EE+.SS Assertions and virtual postings+Balance assertions always consider both real and virtual postings; they+are not affected by the \f[CR]\-\-real/\-R\f[R] flag or \f[CR]real:\f[R]+query.+.SS Assertions and auto postings+Balance assertions \f[I]are\f[R] affected by the \f[CR]\-\-auto\f[R]+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:+.IP \[bu] 2+assert the balance calculated with \f[CR]\-\-auto\f[R], and always use+\f[CR]\-\-auto\f[R] with that file+.IP \[bu] 2+or assert the balance calculated without \f[CR]\-\-auto\f[R], and never+use \f[CR]\-\-auto\f[R] with that file+.IP \[bu] 2+or avoid balance assertions on accounts affected by auto postings (or+avoid auto postings entirely).+.SS 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.+.SS Posting comments+Text following \f[CR];\f[R], at the end of a posting line, and/or on+indented lines immediately below it, form comments for that posting.+They are reproduced by \f[CR]print\f[R] but otherwise ignored, except+they may contain tags, which are not ignored.+.IP+.EX+2012\-01\-01+    expenses   1  ; a comment for posting 1+    assets+    ; a comment for posting 2+    ; a second comment line for posting 2+.EE+.SS 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\[aq] sum perfectly with pencil and paper, hledger should+agree with you.+.PP+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 ?+.PP+hledger currently decides it based on the commodity display styles: if+the postings\[aq] sum would appear to be zero when displayed with the+standard display precisions, the transaction is considered balanced.+.PP+Or equivalently: if the journal entry is displayed with amounts rounded+to the standard display precisions (with+\f[CR]hledger print \-\-round=hard\f[R]), and a human with pencil and+paper would agree that those displayed amounts add up to zero, the+transaction is considered balanced.+.PP+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+\f[CR]\-c/\-\-commodity\-style\f[R] 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).+.PP+Other PTA tools (Ledger, Beancount..)+have their own ways of doing it.+Possible improvements are discussed at #1964.+.PP+Note: if you have multiple journal files, and are relying on commodity+directives to make imprecise journal entries balance, the+directives\[aq] placement might be important \- see \f[CR]commodity\f[R]+directive.+.SS 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.+.PP+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: \f[CR]2024\-01\-01 a transaction   ; foo:\f[R] Note this is an+exception to the usual rule that things in comments are ignored.+.PP+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).+.PP+For example, here are five different tags: one on the+\f[CR]assets:checking\f[R] account, two on the transaction, and two on+the \f[CR]expenses:food\f[R] posting:+.IP+.EX+account assets:checking         ; accounttag:++2017/1/16 bought groceries      ; transactiontag\-1:+    ; transactiontag\-2:+    assets:checking        $\-1+    expenses:food           $1  ; postingtag:, another\-posting\-tag:+.EE+.PP+Postings also inherit tags from their transaction and their account.+And transactions also acquire tags from their postings (and+postings\[aq] 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).+.SS Tag names+Most non\-whitespace characters are allowed in tag names.+Eg \f[CR]😀:\f[R] is a valid tag.+.PP+You can list the tag names used in your journal with the tags command:+.PD 0+.P+.PD+\f[CR]hledger tags [NAMEREGEX]\f[R]+.PP+In commands which use a query, you can match by tag name.+Eg:+.PD 0+.P+.PD+\f[CR]hledger print tag:NAMEREGEX\f[R]+.PP+You can declare valid tag names with the tag directive and then check+them with the check command.+.SS Special tags+Some tag names have special significance to hledger.+There\[aq]s not much harm in using them yourself, but some could produce+an error message, particularly the \f[CR]date:\f[R] and \f[CR]type:\f[R]+tags.+They are explained elsewhere, but here is a quick list for reference:+.PP+Tags you can set to influence hledger\[aq]s behaviour:+.IP+.EX+ date                   \-\- overrides a posting\[aq]s date+ date2                  \-\- overrides a posting\[aq]s secondary date+ type                   \-\- declares an account\[aq]s type+.EE+.PP+Tags hledger adds to indicate generated data:+.IP+.EX+ 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)+.EE+.PP+Tags hledger uses internally:+.IP+.EX+ _conversion\-matched    \-\- exists on postings which have been matched with a nearby \[at]/\[at]\[at] cost annotation+.EE+.SS 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.+.PP+Eg in the following posting, the three tags\[aq] values are \[dq]value+1\[dq], \[dq]value 2\[dq], and \[dq]\[dq] (empty) respectively:+.IP+.EX+    expenses:food   $10    ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz+.EE+.PP+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\[aq]s value or remove a+tag.+.PP+You can list all the values used for a particular tag in the journal+with+.PD 0+.P+.PD+\f[CR]hledger tags TAGNAME \-\-values\f[R]+.PP+You can match on tag values with a query like+\f[CR]tag:NAMEREGEX=VALUEREGEX\f[R]+.SS Directives+Besides transactions, there is something else you can put in a+\f[CR]journal\f[R] file: directives.+These are declarations, beginning with a keyword, that modify+hledger\[aq]s behaviour.+Some directives can have more specific subdirectives, indented below+them.+hledger\[aq]s directives are similar to Ledger\[aq]s in many cases, but+there are also many differences.+Directives are not required, but can be useful.+Here are the main directives:+.PP+.TS+tab(@);+lw(39.7n) lw(30.3n).+T{+purpose+T}@T{+directive+T}+_+T{+\f[B]READING DATA:\f[R]+T}@T{+T}+T{+Rewrite account names+T}@T{+\f[CR]alias\f[R]+T}+T{+Comment out sections of the file+T}@T{+\f[CR]comment\f[R]+T}+T{+Declare file\[aq]s decimal mark, to help parse amounts accurately+T}@T{+\f[CR]decimal\-mark\f[R]+T}+T{+Include other data files+T}@T{+\f[CR]include\f[R]+T}+T{+\f[B]GENERATING DATA:\f[R]+T}@T{+T}+T{+Generate recurring transactions or budget goals+T}@T{+\f[CR]\[ti]\f[R]+T}+T{+Generate extra postings on existing transactions+T}@T{+\f[CR]=\f[R]+T}+T{+\f[B]CHECKING FOR ERRORS:\f[R]+T}@T{+T}+T{+Define valid entities to provide more error checking+T}@T{+\f[CR]account\f[R], \f[CR]commodity\f[R], \f[CR]payee\f[R],+\f[CR]tag\f[R]+T}+T{+\f[B]REPORTING:\f[R]+T}@T{+T}+T{+Declare accounts\[aq] type and display order+T}@T{+\f[CR]account\f[R]+T}+T{+Declare commodity display styles+T}@T{+\f[CR]commodity\f[R]+T}+T{+Declare market prices+T}@T{+\f[CR]P\f[R]+T}+.TE+.SS 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, \f[CR]alias\f[R] directives do not affect parent or sibling+files.+But there are usually workarounds; for example, put \f[CR]alias\f[R]+directives in your top\-most file, before including other files.+.PP+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.+.SS Directive effects+Here are all hledger\[aq]s directives, with their effects and scope+summarised \- nine main directives, plus four others which we consider+non\-essential:+.PP+.TS+tab(@);+lw(3.5n) lw(64.1n) lw(2.4n).+T{+directive+T}@T{+what it does+T}@T{+ends at file end?+T}+_+T{+\f[B]\f[CB]account\f[B]\f[R]+T}@T{+Declares an account, for checking all entries in all files; and its+display order and type.+Subdirectives: any text, ignored.+T}@T{+N+T}+T{+\f[B]\f[CB]alias\f[B]\f[R]+T}@T{+Rewrites account names, in following entries until end of current file+or \f[CR]end aliases\f[R].+Command line equivalent: \f[CR]\-\-alias\f[R]+T}@T{+Y+T}+T{+\f[B]\f[CB]comment\f[B]\f[R]+T}@T{+Ignores part of the journal file, until end of current file or+\f[CR]end comment\f[R].+T}@T{+Y+T}+T{+\f[B]\f[CB]commodity\f[B]\f[R]+T}@T{+Declares up to four things: 1.+a commodity symbol, for checking 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 \f[CR]decimal\-mark\f[R]+directive 4.+the precision to use for balanced\-transaction checking in this+commodity, in this file and its children.+\ Takes precedence over \f[CR]D\f[R].+Subdirectives: \f[CR]format\f[R] (ignored).+Command line equivalent: \f[CR]\-c/\-\-commodity\-style\f[R]+T}@T{+N,N,Y,Y+T}+T{+\f[B]\f[CB]decimal\-mark\f[B]\f[R]+T}@T{+Declares the decimal mark, for parsing amounts of all commodities in+following entries until next \f[CR]decimal\-mark\f[R] or end of current+file.+Included files can override.+Takes precedence over \f[CR]commodity\f[R] and \f[CR]D\f[R].+T}@T{+Y+T}+T{+\f[B]\f[CB]include\f[B]\f[R]+T}@T{+Includes entries and directives from another file, as if they were+written inline.+Command line alternative: multiple \f[CR]\-f/\-\-file\f[R]+T}@T{+N+T}+T{+\f[B]\f[CB]payee\f[B]\f[R]+T}@T{+Declares a payee name, for checking all entries in all files.+T}@T{+N+T}+T{+\f[B]\f[CB]P\f[B]\f[R]+T}@T{+Declares the market price of a commodity on some date, for value+reports.+T}@T{+N+T}+T{+\f[B]\f[CB]\[ti]\f[B]\f[R] (tilde)+T}@T{+Declares a periodic transaction rule that generates future transactions+with \f[CR]\-\-forecast\f[R] and budget goals with+\f[CR]balance \-\-budget\f[R].+T}@T{+N+T}+T{+Other syntax:+T}@T{+T}@T{+T}+T{+\f[B]\f[CB]apply account\f[B]\f[R]+T}@T{+Prepends a common parent account to all account names, in following+entries until end of current file or \f[CR]end apply account\f[R].+T}@T{+Y+T}+T{+\f[B]\f[CB]D\f[B]\f[R]+T}@T{+Sets a default commodity to use for no\-symbol amounts;and, if there is+no \f[CR]commodity\f[R] directive for this commodity: its decimal mark,+balancing precision, and display style, as above.+T}@T{+Y,Y,N,N+T}+T{+\f[B]\f[CB]Y\f[B]\f[R]+T}@T{+Sets a default year to use for any yearless dates, in following entries+until end of current file.+T}@T{+Y+T}+T{+\f[B]\f[CB]=\f[B]\f[R] (equals)+T}@T{+Declares an auto posting rule that generates extra postings on matched+transactions with \f[CR]\-\-auto\f[R], in current, parent, and child+files (but not sibling files, see #1212).+T}@T{+partly+T}+T{+\f[B]Other Ledger directives\f[R]+T}@T{+Other directives from Ledger\[aq]s file format are accepted but ignored.+T}@T{+T}+.TE+.SS \f[CR]account\f[R] directive+\f[CR]account\f[R] 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:+.IP \[bu] 2+They can document your intended chart of accounts, providing a+reference.+.IP \[bu] 2+They can store additional account information as comments, or as tags+which can be used to filter or pivot reports.+.IP \[bu] 2+They can restrict which accounts may be posted to by transactions, eg in+strict mode, which helps prevent errors.+.IP \[bu] 2+They influence account display order in reports, allowing+non\-alphabetic sorting (eg Revenues to appear above Expenses).+.IP \[bu] 2+They can help hledger know your accounts\[aq] types (asset, liability,+equity, revenue, expense), enabling reports like balancesheet and+incomestatement.+.IP \[bu] 2+They help with account name completion (in hledger add, hledger\-web,+hledger\-iadd, ledger\-mode, etc.)+.PP+They are written as the word \f[CR]account\f[R] followed by a+hledger\-style account name.+Eg:+.IP+.EX+account assets:bank:checking+.EE+.PP+Ledger\-style indented subdirectives are also accepted, but ignored:+.IP+.EX+account assets:bank:checking+  format subdirective  ; currently ignored+.EE+.SS Account comments+Text following \f[B]two or more spaces\f[R] and \f[CR];\f[R] at the end+of an account directive line, and/or following \f[CR];\f[R] on indented+lines immediately below it, form comments for that account.+They are ignored except they may contain tags, which are not ignored.+.PP+The two\-space requirement for same\-line account comments is because+\f[CR];\f[R] is allowed in account names.+.IP+.EX+account assets:bank:checking    ; same\-line comment, at least 2 spaces before the semicolon+  ; next\-line comment+  ; some tags \- type:A, acctnum:12345+.EE+.SS 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\[aq]t warn you when you+mis\-spell an account name in the journal.+Usually you\[aq]ll find that error later, as an extra account in balance+reports, or an incorrect balance when reconciling.+.PP+In strict mode, enabled with the \f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R]+flag, hledger will report an error if any transaction uses an account+name that has not been declared by an account directive.+Some notes:+.IP \[bu] 2+The declaration is case\-sensitive; transactions must use the correct+account name capitalisation.+.IP \[bu] 2+The account directive\[aq]s scope is \[dq]whole file and below\[dq] (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\[aq]s usual to put them at the top.+.IP \[bu] 2+Accounts can only be declared in \f[CR]journal\f[R] files, but will+affect included files of all types.+.IP \[bu] 2+It\[aq]s currently not possible to declare \[dq]all possible+subaccounts\[dq] with a wildcard; every account posted to must be+declared.+.SS 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:+.IP+.EX+account assets+account liabilities+account equity+account revenues+account expenses+.EE+.PP+Now hledger displays them in that order:+.IP+.EX+$ hledger accounts+assets+liabilities+equity+revenues+expenses+.EE+.PP+If there are undeclared accounts, those will be displayed last, in+alphabetical order.+.PP+Sorting is done within each group of sibling accounts, at each level of+the account tree.+Eg, a declaration like \f[CR]account parent:child\f[R] influences+\f[CR]child\f[R]\[aq]s position among its siblings.+.PP+Note, it does not affect \f[CR]parent\f[R]\[aq]s position; for that, you+need an \f[CR]account parent\f[R] declaration.+.PP+Sibling accounts are always displayed together; hledger won\[aq]t+display \f[CR]x:y\f[R] in between \f[CR]a:b\f[R] and \f[CR]a:c\f[R].+.PP+An account directive both declares an account as a valid posting target,+and declares its display order; you can\[aq]t easily do one without the+other.+.SS 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 \f[CR]type:\f[R] query.+.PP+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\[aq]s more robust to declare accounts\[aq] types explicitly, by+adding \f[CR]type:\f[R] tags to their account directives.+The tag\[aq]s value should be one of the five main account types:+.IP \[bu] 2+\f[CR]A\f[R] or \f[CR]Asset\f[R] (things you own)+.IP \[bu] 2+\f[CR]L\f[R] or \f[CR]Liability\f[R] (things you owe)+.IP \[bu] 2+\f[CR]E\f[R] or \f[CR]Equity\f[R] (investment/ownership; balanced+counterpart of assets & liabilities)+.IP \[bu] 2+\f[CR]R\f[R] or \f[CR]Revenue\f[R] (what you received money from, AKA+income; technically part of Equity)+.IP \[bu] 2+\f[CR]X\f[R] or \f[CR]Expense\f[R] (what you spend money on; technically+part of Equity)+.PP+or, it can be (these are used less often):+.IP \[bu] 2+\f[CR]C\f[R] or \f[CR]Cash\f[R] (a subtype of Asset, indicating liquid+assets for the cashflow report)+.IP \[bu] 2+\f[CR]V\f[R] or \f[CR]Conversion\f[R] (a subtype of Equity, for+conversions (see Cost reporting).)+.PP+Subaccounts inherit their parent\[aq]s type, or they can override it.+Here is a typical set of account type declarations:+.IP+.EX+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+.EE+.PP+Here are some tips for working with account types.+.IP \[bu] 2+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\[aq]t work for you, just ignore them and declare your account+types.+See also Regular expressions.+.RS 2+.IP+.EX+If account\[aq]s name contains this (CI) regular expression:            | its type is:+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-+\[ha]assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|current)(:|$) | Cash+\[ha]assets?(:|$)                                                       | Asset+\[ha](debts?|liabilit(y|ies))(:|$)                                      | Liability+\[ha]equity:(trad(e|ing)|conversion)s?(:|$)                             | Conversion+\[ha]equity(:|$)                                                        | Equity+\[ha](income|revenue)s?(:|$)                                            | Revenue+\[ha]expenses?(:|$)                                                     | Expense+.EE+.RE+.IP \[bu] 2+If you declare any account types, it\[aq]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.+.IP \[bu] 2+Certain uses of account aliases can disrupt account types.+See Rewriting accounts > Aliases and account types.+.IP \[bu] 2+As mentioned above, subaccounts will inherit a type from their parent+account.+More precisely, an account\[aq]s type is decided by the first of these+that exists:+.RS 2+.IP "1." 3+A \f[CR]type:\f[R] declaration for this account.+.IP "2." 3+A \f[CR]type:\f[R] declaration in the parent accounts above it,+preferring the nearest.+.IP "3." 3+An account type inferred from this account\[aq]s name.+.IP "4." 3+An account type inferred from a parent account\[aq]s name, preferring+the nearest parent.+.IP "5." 3+Otherwise, it will have no type.+.RE+.IP \[bu] 2+For troubleshooting, you can list accounts and their types with:+.RS 2+.IP+.EX+$ hledger accounts \-\-types [ACCTPAT] [\-DEPTH] [type:TYPECODES]+.EE+.RE+.SS \f[CR]alias\f[R] directive+You can define account alias rules which rewrite your account names, or+parts of them, before generating reports.+This can be useful for:+.IP \[bu] 2+expanding shorthand account names to their full form, allowing easier+data entry and a less verbose journal+.IP \[bu] 2+adapting old journals to your current chart of accounts+.IP \[bu] 2+experimenting with new account organisations, like a new hierarchy+.IP \[bu] 2+combining two accounts into one, eg to see their sum or difference on+one line+.IP \[bu] 2+customising reports+.PP+Account aliases also rewrite account names in account directives.+They do not affect account names being entered via hledger add or+hledger\-web.+.PP+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.+.PP+See also Rewrite account names.+.SS Basic aliases+To set an account alias, use the \f[CR]alias\f[R] 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:+.IP+.EX+alias OLD = NEW+.EE+.PP+Or, you can use the \f[CR]\-\-alias \[aq]OLD=NEW\[aq]\f[R] option on the+command line.+This affects all entries.+It\[aq]s useful for trying out aliases interactively.+.PP+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:+.IP+.EX+alias checking = assets:bank:wells fargo:checking+; rewrites \[dq]checking\[dq] to \[dq]assets:bank:wells fargo:checking\[dq], or \[dq]checking:a\[dq] to \[dq]assets:bank:wells fargo:checking:a\[dq]+.EE+.SS 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.)+.PP+Eg:+.IP+.EX+alias /REGEX/ = REPLACEMENT+.EE+.PP+or:+.IP+.EX+$ hledger \-\-alias \[aq]/REGEX/=REPLACEMENT\[aq] ...+.EE+.PP+Any part of an account name matched by REGEX will be replaced by+REPLACEMENT.+REGEX is case\-insensitive as usual.+.PP+If you need to match a forward slash, escape it with a backslash, eg+\f[CR]/\[rs]/=:\f[R].+.PP+If REGEX contains parenthesised match groups, these can be referenced by+the usual backslash and number in REPLACEMENT:+.IP+.EX+alias /\[ha](.+):bank:([\[ha]:]+):(.*)/ = \[rs]1:\[rs]2 \[rs]3+; rewrites \[dq]assets:bank:wells fargo:checking\[dq] to  \[dq]assets:wells fargo checking\[dq]+.EE+.PP+REPLACEMENT continues to the end of line (or on command line, to end of+option argument), so it can contain trailing whitespace.+.SS Combining aliases+You can define as many aliases as you like, using journal directives+and/or command line options.+.PP+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.+.PP+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:+.IP "1." 3+\f[CR]alias\f[R] directives preceding the journal entry, most recently+parsed first (ie, reading upward from the journal entry, bottom to top)+.IP "2." 3+\f[CR]\-\-alias\f[R] options, in the order they appeared on the command+line (left to right).+.PP+In other words, for (an account name in) a given journal entry:+.IP \[bu] 2+the nearest alias declaration before/above the entry is applied first+.IP \[bu] 2+the next alias before/above that will be be applied next, and so on+.IP \[bu] 2+aliases defined after/below the entry do not affect it.+.PP+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.+.PP+In case of trouble, adding \f[CR]\-\-debug=6\f[R] to the command line+will show which aliases are being applied when.+.SS Aliases and multiple files+As explained at Directives and multiple files, \f[CR]alias\f[R]+directives do not affect parent or sibling files.+Eg in this command,+.IP+.EX+hledger \-f a.aliases \-f b.journal+.EE+.PP+account aliases defined in a.aliases will not affect b.journal.+Including the aliases doesn\[aq]t work either:+.IP+.EX+include a.aliases++2023\-01\-01  ; not affected by a.aliases+  foo  1+  bar+.EE+.PP+This means that account aliases should usually be declared at the start+of your top\-most file, like this:+.IP+.EX+alias foo=Foo+alias bar=Bar++2023\-01\-01  ; affected by aliases above+  foo  1+  bar++include c.journal  ; also affected+.EE+.SS \f[CR]end aliases\f[R] directive+You can clear (forget) all currently defined aliases (seen in the+journal so far, or defined on the command line) with this directive:+.IP+.EX+end aliases+.EE+.SS Aliases can generate bad account names+Be aware that account aliases can produce malformed account names, which+could cause confusing reports or invalid \f[CR]print\f[R] output.+For example, you could erase all account names:+.IP+.EX+2021\-01\-01+  a:aa     1+  b+.EE+.IP+.EX+$ hledger print \-\-alias \[aq]/.*/=\[aq]+2021\-01\-01+                   1+.EE+.PP+The above \f[CR]print\f[R] output is not a valid journal.+Or you could insert an illegal double space, causing \f[CR]print\f[R]+output that would give a different journal when reparsed:+.IP+.EX+2021\-01\-01+  old    1+  other+.EE+.IP+.EX+$ hledger print \-\-alias old=\[dq]new  USD\[dq] | hledger \-f\- print+2021\-01\-01+    new             USD 1+    other+.EE+.SS 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.+.PP+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.+.PP+Secondly, if an account\[aq]s type is being inferred from its name,+renaming it by an alias could prevent or alter that.+.PP+If you are using account aliases and the \f[CR]type:\f[R] query is not+matching accounts as you expect, try troubleshooting with the accounts+command, eg something like:+.IP+.EX+$ hledger accounts \-\-alias assets=bassetts type:a+.EE+.SS \f[CR]commodity\f[R] directive+The \f[CR]commodity\f[R] directive performs several functions:+.IP "1." 3+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.+.IP "2." 3+It declares how all amounts in this commodity should be displayed, eg+how many decimals to show.+See Commodity display style above.+.IP "3." 3+(If no \f[CR]decimal\-mark\f[R] 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.+.IP "4." 3+It declares the precision with which this commodity\[aq]s amounts should+be compared when checking for balanced transactions, anywhere in this+file and files it includes, until end of current file.+.PP+Declaring commodities solves several common parsing/display problems, so+we recommend it.+.PP+Note that effects 3 and 4 above end at the end of the directive\[aq]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.+.PP+(Related: #793)+.SS Commodity directive syntax+A commodity directive is normally the word \f[CR]commodity\f[R] followed+by a sample amount (and optionally a comment).+Only the amount\[aq]s symbol and format is significant.+Eg:+.IP+.EX+commodity $1000.00+commodity 1.000,00 EUR+commodity 1 000 000.0000   ; the no\-symbol commodity+.EE+.PP+Commodities do not have tags (tags in the comment will be ignored).+.PP+A commodity directive\[aq]s sample amount must always include a period+or comma decimal mark (this rule helps disambiguate decimal marks and+digit group marks).+If you don\[aq]t want to show any decimal digits, write the decimal mark+at the end:+.IP+.EX+commodity 1000. AAAA       ; show AAAA with no decimals+.EE+.PP+Commodity symbols containing spaces, numbers, or punctuation must be+enclosed in double quotes, as usual:+.IP+.EX+commodity 1.0000 \[dq]AAAA 2023\[dq]+.EE+.PP+Commodity directives normally include a sample amount, but can declare+only a symbol (ie, just function 1 above):+.IP+.EX+commodity $+commodity INR+commodity \[dq]AAAA 2023\[dq]+commodity \[dq]\[dq]               ; the no\-symbol commodity+.EE+.PP+Commodity directives may also be written with an indented+\f[CR]format\f[R] subdirective, as in Ledger.+The symbol is repeated and must be the same in both places.+Other subdirectives are currently ignored:+.IP+.EX+; 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+.EE+.SS Commodity error checking+In strict mode (\f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R]) (or when you run+\f[CR]hledger check commodities\f[R]), 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).+.SS \f[CR]decimal\-mark\f[R] directive+You can use a \f[CR]decimal\-mark\f[R] 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+.IP+.EX+decimal\-mark .+.EE+.PP+or+.IP+.EX+decimal\-mark ,+.EE+.PP+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).+.SS \f[CR]include\f[R] directive+You can pull in the content of additional files by writing an include+directive, like this:+.IP+.EX+include FILEPATH+.EE+.PP+Only journal files can include, and only journal, timeclock or timedot+files can be included (not CSV files, currently).+.PP+If the file path does not begin with a slash, it is relative to the+current file\[aq]s folder.+.PP+A tilde means home directory, eg: \f[CR]include \[ti]/main.journal\f[R].+.PP+The path may contain glob patterns to match multiple files, eg:+\f[CR]include *.journal\f[R].+.PP+There is limited support for recursive wildcards: \f[CR]**/\f[R] (the+slash is required) matches 0 or more subdirectories.+It\[aq]s not super convenient since you have to avoid include cycles and+including directories, but this can be done, eg:+\f[CR]include */**/*.journal\f[R].+.PP+The path may also be prefixed to force a specific file format,+overriding the file extension (as described in Data formats):+\f[CR]include timedot:\[ti]/notes/2023*.md\f[R].+.SS \f[CR]P\f[R] directive+The \f[CR]P\f[R] 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.+.PP+The format is:+.IP+.EX+P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT+.EE+.PP+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:+.IP+.EX+# 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+.EE+.PP+The \f[CR]\-V\f[R], \f[CR]\-X\f[R] and \f[CR]\-\-value\f[R] flags use+these market prices to show amount values in another commodity.+See Value reporting.+.PP+.SS \f[CR]payee\f[R] directive+\f[CR]payee PAYEE NAME\f[R]+.PP+This directive can be used to declare a limited set of payees which may+appear in transaction descriptions.+The \[dq]payees\[dq] check will report an error if any transaction+refers to a payee that has not been declared.+Eg:+.IP+.EX+payee Whole Foods    ; a comment+.EE+.PP+Payees do not have tags (tags in the comment will be ignored).+.PP+To declare the empty payee name, use \f[CR]\[dq]\[dq]\f[R].+.IP+.EX+payee \[dq]\[dq]+.EE+.PP+Ledger\-style indented subdirectives, if any, are currently ignored.+.SS \f[CR]tag\f[R] directive+\f[CR]tag TAGNAME\f[R]+.PP+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:+.IP+.EX+tag  item\-id+.EE+.PP+Any indented subdirectives are currently ignored.+.PP+The \[dq]tags\[dq] 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 .+.SS Periodic transactions+The \f[CR]\[ti]\f[R] directive declares a \[dq]periodic rule\[dq] which+generates temporary extra transactions, usually recurring at some+interval, when hledger is run with the \f[CR]\-\-forecast\f[R] flag.+These \[dq]forecast transactions\[dq] are useful for forecasting future+activity.+They exist only for the duration of the report, and only when+\f[CR]\-\-forecast\f[R] is used; they are not saved in the journal file+by hledger.+.PP+Periodic rules also have a second use: with the \f[CR]\-\-budget\f[R]+flag they set budget goals for budgeting.+.PP+Periodic rules can be a little tricky, so before you use them, read this+whole section, or at least the following tips:+.IP "1." 3+Two spaces accidentally added or omitted will cause you trouble \- read+about this below.+.IP "2." 3+For troubleshooting, show the generated transactions with+\f[CR]hledger print \-\-forecast tag:generated\f[R] or+\f[CR]hledger register \-\-forecast tag:generated\f[R].+.IP "3." 3+Forecasted transactions will begin only after the last non\-forecasted+transaction\[aq]s date.+.IP "4." 3+Forecasted transactions will end 6 months from today, by default.+See below for the exact start/end rules.+.IP "5." 3+period expressions can be tricky.+Their documentation needs improvement, but is worth studying.+.IP "6." 3+Some period expressions with a repeating interval must begin on a+natural boundary of that interval.+Eg in \f[CR]weekly from DATE\f[R], DATE must be a monday.+\f[CR]\[ti] weekly from 2019/10/1\f[R] (a tuesday) will give an error.+.IP "7." 3+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\[aq]s a bit inconsistent with the above.)+Eg:  \f[CR]\[ti] every 10th day of month from 2023/01\f[R], which is+equivalent to  \f[CR]\[ti] every 10th day of month from 2023/01/01\f[R],+will be adjusted to start on 2019/12/10.+.SS Periodic rule syntax+A periodic transaction rule looks like a normal journal entry, with the+date replaced by a tilde (\f[CR]\[ti]\f[R]) followed by a period+expression (mnemonic: \f[CR]\[ti]\f[R] looks like a recurring sine+wave.):+.IP+.EX+# every first of month+\[ti] monthly+    expenses:rent          $2000+    assets:bank:checking++# every 15th of month in 2023\[aq]s first quarter:+\[ti] monthly from 2023\-04\-15 to 2023\-06\-16+    expenses:utilities          $400+    assets:bank:checking+.EE+.PP+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\[aq]+start dates).+.SS Periodic rules and relative dates+Partial or relative dates (like \f[CR]12/31\f[R], \f[CR]25\f[R],+\f[CR]tomorrow\f[R], \f[CR]last week\f[R], \f[CR]next quarter\f[R]) 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:+.IP "1." 3+the first day of the default year specified by a recent \f[CR]Y\f[R]+directive+.IP "2." 3+or the date specified with \f[CR]\-\-today\f[R]+.IP "3." 3+or the date on which you are running the report.+.PP+They will not be affected at all by report period or forecast period+dates.+.SS Two spaces between period expression and description!+If the period expression is followed by a transaction description, these+must be separated by \f[B]two or more spaces\f[R].+This helps hledger know where the period expression ends, so that+descriptions can not accidentally alter their meaning, as in this+example:+.IP+.EX+; 2 or more spaces needed here, so the period is not understood as \[dq]every 2 months in 2023\[dq]+;               ||+;               vv+\[ti] every 2 months  in 2023, we will review+    assets:bank:checking   $1500+    income:acme inc+.EE+.PP+So,+.IP \[bu] 2+Do write two spaces between your period expression and your transaction+description, if any.+.IP \[bu] 2+Don\[aq]t accidentally write two spaces in the middle of your period+expression.+.SS Auto postings+The \f[CR]=\f[R] directive declares an \[dq]auto posting rule\[dq],+which adds extra postings to existing transactions.+(Remember, postings are the account name & amount lines below a+transaction\[aq]s date & description.)+.PP+In the journal, an auto posting rule looks quite like a transaction, but+instead of date and description it has \f[CR]=\f[R] (mnemonic:+\[dq]match\[dq]) and a query, like this:+.IP+.EX+= QUERY+    ACCOUNT    AMOUNT+    ...+.EE+.PP+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.+.PP+Each \f[CR]=\f[R] rule works like this: when hledger is run with the+\f[CR]\-\-auto\f[R] flag, wherever the QUERY matches a posting in the+journal, the rule\[aq]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 \f[CR]\-\-auto\f[R] is used; they+are not saved in the journal file by hledger.+.PP+Generated postings\[aq] amounts can depend on the matched posting\[aq]s+amount.+So auto postings can be useful for, eg, adding tax postings with a+standard percentage.+AMOUNT can be:+.IP \[bu] 2+a number with no commodity symbol, like \f[CR]2\f[R].+The matched posting\[aq]s commodity symbol will be added to this.+.IP \[bu] 2+a normal amount with a commodity symbol, like \f[CR]$2\f[R].+This will be used as\-is.+.IP \[bu] 2+an asterisk followed by a number, like \f[CR]*2\f[R].+This will multiply the matched posting\[aq]s amount (and total price, if+any) by the number.+.IP \[bu] 2+an asterisk followed by an amount with commodity symbol, like+\f[CR]*$2\f[R].+This multiplies and also replaces the commodity symbol with this new+one.+.PP+Some examples:+.IP+.EX+; 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+.EE+.IP+.EX+$ 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+.EE+.PP+Note that depending fully on generated data such as this has some+drawbacks \- it\[aq]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\[aq]t use \f[CR]\-\-auto\f[R]).+An alternative is to use auto postings in \[dq]one time\[dq] fashion \-+use them to help build a complex journal entry, view it with+\f[CR]hledger print \-\-auto\f[R], and then copy that output into the+journal file to make it permanent.+.SS 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[CR]\-f\f[R]/\f[CR]\-\-file\f[R] are used \- see #1212).+.SS 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.+.SS Auto postings and transaction balancing / inferred amounts / balance assertions+Currently, auto postings are added:+.IP \[bu] 2+after missing amounts are inferred, and transactions are checked for+balancedness,+.IP \[bu] 2+but before balance assertions are checked.+.PP+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.+.PP+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.+.SS Auto posting tags+Automated postings will have some extra tags:+.IP \[bu] 2+\f[CR]generated\-posting:= QUERY\f[R] \- shows this was generated by an+auto posting rule, and the query+.IP \[bu] 2+\f[CR]_generated\-posting:= QUERY\f[R] \- a hidden tag, which does not+appear in hledger\[aq]s output.+This can be used to match postings generated \[dq]just now\[dq], rather+than generated in the past and saved to the journal.+.PP+Also, any transaction that has been changed by auto posting rules will+have these tags added:+.IP \[bu] 2+\f[CR]modified:\f[R] \- this transaction was modified+.IP \[bu] 2+\f[CR]_modified:\f[R] \- a hidden tag not appearing in the comment; this+transaction was modified \[dq]just now\[dq].+.SS 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+\f[CR]tag:_generated\-transaction\f[R] to their QUERY.+This can be useful when generating new journal entries to be saved in+the journal.+.SS 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.+.SS 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:+.IP+.EX+; 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+.EE+.PP+or when adjusting a balance to reality:+.IP+.EX+; no cash left; update balance, record any untracked spending as a generic expense+2016/1/15+  assets:cash    = $0+  expenses:misc+.EE+.PP+The calculated amount depends on the account\[aq]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).+.PP+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\[aq] forcing of balances can hide errors.+These things make your financial data less portable, less future\-proof,+and less trustworthy in an audit.+.SS Balance assignments and costs+A cost in a balance assignment will cause the calculated amount to have+that cost attached:+.IP+.EX+2019/1/1+  (a)             = $1 \[at] €2+.EE+.IP+.EX+$ hledger print \-\-explicit+2019\-01\-01+    (a)         $1 \[at] €2 = $1 \[at] €2+.EE+.SS 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.+.SS Bracketed posting dates+For setting posting dates and secondary posting dates, Ledger\[aq]s+bracketed date syntax is also supported: \f[CR][DATE]\f[R],+\f[CR][DATE=DATE2]\f[R] or \f[CR][=DATE2]\f[R] in posting comments.+hledger will attempt to parse any square\-bracketed sequence of the+\f[CR]0123456789/\-.=\f[R] characters in this way.+With this syntax, DATE infers its year from the transaction and DATE2+infers its year from DATE.+.PP+Downsides: another syntax to learn, redundant with hledger\[aq]s+\f[CR]date:\f[R]/\f[CR]date2:\f[R] tags, and confusingly similar to+Ledger\[aq]s lot date syntax.+.SS \f[CR]D\f[R] directive+\f[CR]D AMOUNT\f[R]+.PP+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 \f[CR]D\f[R] directive, or the end of+the current file.+.PP+For compatibility/historical reasons, \f[CR]D\f[R] also acts like a+\f[CR]commodity\f[R] directive (setting the commodity\[aq]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:+.IP+.EX+; 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+.EE+.PP+Interactions with other directives:+.PP+For setting a commodity\[aq]s display style, a \f[CR]commodity\f[R]+directive has highest priority, then a \f[CR]D\f[R] directive.+.PP+For detecting a commodity\[aq]s decimal mark during parsing,+\f[CR]decimal\-mark\f[R] has highest priority, then+\f[CR]commodity\f[R], then \f[CR]D\f[R].+.PP+For checking commodity symbols with the check command, a+\f[CR]commodity\f[R] directive is required+(\f[CR]hledger check commodities\f[R] ignores \f[CR]D\f[R] directives).+.PP+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 \f[CR]commodity\f[R] and+\f[CR]decimal\-mark\f[R].+And it works differently from Ledger\[aq]s \f[CR]D\f[R].+.SS \f[CR]apply account\f[R] directive+This directive sets a default parent account, which will be prepended to+all accounts in following entries, until an \f[CR]end apply account\f[R]+directive or end of current file.+Eg:+.IP+.EX+apply account home++2010/1/1+    food    $10+    cash++end apply account+.EE+.PP+is equivalent to:+.IP+.EX+2010/01/01+    home:food           $10+    home:cash          $\-10+.EE+.PP+\f[CR]account\f[R] directives are also affected, and so is any+\f[CR]include\f[R]d content.+.PP+Account names entered via hledger add or hledger\-web are not affected.+.PP+Account aliases, if any, are applied after the parent account is+prepended.+.PP+Downsides: this can make your financial data less explicit, less+portable, and less trustworthy in an audit.+.SS \f[CR]Y\f[R] directive+\f[CR]Y YEAR\f[R]+.PP+or (deprecated backward\-compatible forms):+.PP+\f[CR]year YEAR\f[R] \f[CR]apply year YEAR\f[R]+.PP+The space is optional.+This sets a default year to be used for subsequent dates which don\[aq]t+specify a year.+Eg:+.IP+.EX+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+.EE+.PP+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\[aq]s date.+.SS Secondary dates+A secondary date is written after the primary date, following an equals+sign: \f[CR]DATE1=DATE2\f[R].+If the year is omitted, the primary date\[aq]s year is assumed.+When running reports, the primary (left side) date is used by default,+but with the \f[CR]\-\-date2\f[R] flag (\f[CR]\-\-aux\-date\f[R]+or\f[CR]\-\-effective\f[R] also work, for Ledger users), the secondary+(right side) date will be used instead.+.PP+The meaning of secondary dates is up to you.+Eg it could be \[dq]primary is the bank\[aq]s clearing date, secondary+is the date the transaction was initiated, if different\[dq].+.PP+In practice, this feature usually adds confusion:+.IP \[bu] 2+You have to remember the primary and secondary dates\[aq] meaning, and+follow that consistently.+.IP \[bu] 2+It splits your bookkeeping into two modes, and you have to remember+which mode is appropriate for a given report.+.IP \[bu] 2+Usually your balance assertions will work with only one of these modes.+.IP \[bu] 2+It makes your financial data more complicated, less portable, and less+clear in an audit.+.IP \[bu] 2+It interacts with every feature, creating an ongoing cost for+implementors.+.IP \[bu] 2+It distracts new users and supporters.+.IP \[bu] 2+Posting dates are simpler and work better.+.PP+So secondary dates are officially deprecated in hledger, remaining only+as a Ledger compatibility aid; we recommend using posting dates instead.+.SS Star comments+Lines beginning with \f[CR]*\f[R] (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.+.PP+Downsides: another, unconventional comment syntax to learn.+Decreases your journal\[aq]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\[aq]s features.+.SS Valuation expressions+Ledger allows a valuation function or value to be written in double+parentheses after an amount.+hledger ignores these.+.SS Virtual postings+A posting with parentheses around the account name, like+\f[CR](some:account)   10\f[R], is called an \f[I]unbalanced virtual+posting\f[R].+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.+.PP+A posting with brackets around the account name+(\f[CR][some:account]\f[R]) is called a \f[I]balanced virtual+posting\f[R].+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:+.IP+.EX+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+.EE+.PP+Ordinary postings, whose account names are neither parenthesised nor+bracketed, are called \f[I]real postings\f[R].+You can exclude virtual postings from reports with the+\f[CR]\-R/\-\-real\f[R] flag or a \f[CR]real:1\f[R] query.+.SS 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\[aq]s reports may differ from Ledger\[aq]s if you use these.+.IP+.EX+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+.EE+.PP+See also https://hledger.org/ledger.html for a detailed hledger/Ledger+syntax comparison.+.SS Other cost/lot notations+A slight digression for Ledger and Beancount users.+Ledger has a number of cost/lot\-related notations:+.IP \[bu] 2+\f[CR]\[at] UNITCOST\f[R] and \f[CR]\[at]\[at] TOTALCOST\f[R]+.RS 2+.IP \[bu] 2+expresses a conversion rate, as in hledger+.IP \[bu] 2+when buying, also creates a lot than can be selected at selling time+.RE+.IP \[bu] 2+\f[CR](\[at]) UNITCOST\f[R] and \f[CR](\[at]\[at]) TOTALCOST\f[R]+(virtual cost)+.RS 2+.IP \[bu] 2+like the above, but also means \[dq]this cost was exceptional, don\[aq]t+use it when inferring market prices\[dq].+.RE+.PP+Currently, hledger treats the above like \f[CR]\[at]\f[R] and+\f[CR]\[at]\[at]\f[R]; the parentheses are ignored.+.IP \[bu] 2+\f[CR]{=FIXEDUNITCOST}\f[R] and \f[CR]{{=FIXEDTOTALCOST}}\f[R] (fixed+price)+.RS 2+.IP \[bu] 2+when buying, means \[dq]this cost is also the fixed price, don\[aq]t let+it fluctuate in value reports\[dq]+.RE+.IP \[bu] 2+\f[CR]{UNITCOST}\f[R] and \f[CR]{{TOTALCOST}}\f[R] (lot price)+.RS 2+.IP \[bu] 2+can be used identically to \f[CR]\[at] UNITCOST\f[R] and+\f[CR]\[at]\[at] TOTALCOST\f[R], also creates a lot+.IP \[bu] 2+when selling, combined with \f[CR]\[at] ...\f[R], specifies an+investment lot by its cost basis; does not check if that lot is present+.RE+.IP \[bu] 2+and related: \f[CR][YYYY/MM/DD]\f[R] (lot date)+.RS 2+.IP \[bu] 2+when buying, attaches this acquisition date to the lot+.IP \[bu] 2+when selling, selects a lot by its acquisition date+.RE+.IP \[bu] 2+\f[CR](SOME TEXT)\f[R] (lot note)+.RS 2+.IP \[bu] 2+when buying, attaches this note to the lot+.IP \[bu] 2+when selling, selects a lot by its note+.RE+.PP+Currently, hledger accepts any or all of the above in any order after+the posting amount, but ignores them.+(This can break transaction balancing.)+.PP+For Beancount users, the notation and behaviour is different:+.IP \[bu] 2+\f[CR]\[at] UNITCOST\f[R] and \f[CR]\[at]\[at] TOTALCOST\f[R]+.RS 2+.IP \[bu] 2+expresses a cost without creating a lot, as in hledger+.IP \[bu] 2+when buying (augmenting) or selling (reducing) a lot, combined with+\f[CR]{...}\f[R]: documents the cost/selling price (not used for+transaction balancing)+.RE+.IP \[bu] 2+\f[CR]{UNITCOST}\f[R] and \f[CR]{{TOTALCOST}}\f[R]+.RS 2+.IP \[bu] 2+when buying (augmenting), expresses the cost for transaction balancing,+and also creates a lot with this cost basis attached+.IP \[bu] 2+when selling (reducing),+.RS 2+.IP \[bu] 2+selects a lot by its cost basis+.IP \[bu] 2+raises an error if that lot is not present or can not be selected+unambiguously (depending on booking method configured)+.IP \[bu] 2+expresses the selling price for transaction balancing+.RE+.RE+.PP+Currently, hledger accepts the+\f[CR]{UNITCOST}\f[R]/\f[CR]{{TOTALCOST}}\f[R] notation but ignores it.+.IP \[bu] 2+variations: \f[CR]{}\f[R], \f[CR]{YYYY\-MM\-DD}\f[R],+\f[CR]{\[dq]LABEL\[dq]}\f[R], \f[CR]{UNITCOST, \[dq]LABEL\[dq]}\f[R],+\f[CR]{UNITCOST, YYYY\-MM\-DD, \[dq]LABEL\[dq]}\f[R] etc.+.PP+Currently, hledger rejects these.+.PP+.SH CSV+hledger can read CSV files (Character Separated Value \- usually comma,+semicolon, or tab) containing dated records, automatically converting+each record into a transaction.+.PP+(To learn about \f[I]writing\f[R] CSV, see CSV output.)+.PP+For best error messages when reading CSV/TSV/SSV files, make sure they+have a corresponding \f[CR].csv\f[R], \f[CR].tsv\f[R] or \f[CR].ssv\f[R]+file extension or use a hledger file prefix (see File Extension below).+.PP+Each CSV file must be described by a corresponding \f[I]rules file\f[R].+.PD 0+.P+.PD+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.+.PP+By default, hledger expects this rules file to be named like the CSV+file, with an extra \f[CR].rules\f[R] extension added, in the same+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.+.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+are.+Here\[aq]s a simple CSV file and a rules file for it:+.IP+.EX+Date, Description, Id, Amount+12/11/2019, Foo, 123, 10.23+.EE+.IP+.EX+# basic.csv.rules+skip         1+fields       date, description, , amount+date\-format  %d/%m/%Y+.EE+.IP+.EX+$ hledger print \-f basic.csv+2019\-11\-12 Foo+    expenses:unknown           10.23+    income:unknown            \-10.23+.EE+.PP+There\[aq]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.+.SS CSV rules cheatsheet+The following kinds of rule can appear in the rules file, in any order.+(Blank lines and lines beginning with \f[CR]#\f[R] or \f[CR];\f[R] or+\f[CR]*\f[R] are ignored.)+.PP+.TS+tab(@);+lw(23.7n) lw(46.3n).+T{+\f[B]\f[CB]source\f[B]\f[R]+T}@T{+optionally declare which file to read data from+T}+T{+\f[B]\f[CB]separator\f[B]\f[R]+T}@T{+declare the field separator, instead of relying on file extension+T}+T{+\f[B]\f[CB]skip\f[B]\f[R]+T}@T{+skip one or more header lines at start of file+T}+T{+\f[B]\f[CB]date\-format\f[B]\f[R]+T}@T{+declare how to parse CSV dates/date\-times+T}+T{+\f[B]\f[CB]timezone\f[B]\f[R]+T}@T{+declare the time zone of ambiguous CSV date\-times+T}+T{+\f[B]\f[CB]newest\-first\f[B]\f[R]+T}@T{+improve txn order when: there are multiple records, newest first, all+with the same date+T}+T{+\f[B]\f[CB]intra\-day\-reversed\f[B]\f[R]+T}@T{+improve txn order when: same\-day txns are in opposite order to the+overall file+T}+T{+\f[B]\f[CB]decimal\-mark\f[B]\f[R]+T}@T{+declare the decimal mark used in CSV amounts, when ambiguous+T}+T{+\f[B]\f[CB]fields\f[B] list\f[R]+T}@T{+name CSV fields for easy reference, and optionally assign their values+to hledger fields+T}+T{+\f[B]Field assignment\f[R]+T}@T{+assign a CSV value or interpolated text value to a hledger field+T}+T{+\f[B]\f[CB]if\f[B] block\f[R]+T}@T{+conditionally assign values to hledger fields, or \f[CR]skip\f[R] a+record or \f[CR]end\f[R] (skip rest of file)+T}+T{+\f[B]\f[CB]if\f[B] table\f[R]+T}@T{+conditionally assign values to hledger fields, using compact syntax+T}+T{+\f[B]\f[CB]balance\-type\f[B]\f[R]+T}@T{+select which type of balance assertions/assignments to generate+T}+T{+\f[B]\f[CB]include\f[B]\f[R]+T}@T{+inline another CSV rules file+T}+.TE+.PP+Working with CSV tips can be found below, including How CSV rules are+evaluated.+.SS \f[CR]source\f[R]+If you tell hledger to read a csv file with \f[CR]\-f foo.csv\f[R], it+will look for rules in \f[CR]foo.csv.rules\f[R].+Or, you can tell it to read the rules file, with+\f[CR]\-f foo.csv.rules\f[R], and it will look for data in+\f[CR]foo.csv\f[R] (since 1.30).+.PP+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 \[dq]source\[dq]+rule:+.IP+.EX+source ./Checking1.csv+.EE+.PP+If you specify just a file name with no path, hledger will look for it+in your system\[aq]s downloads directory (\f[CR]\[ti]/Downloads\f[R],+currently):+.IP+.EX+source Checking1.csv+.EE+.PP+And if you specify a glob pattern, hledger will read the most recent of+the matched files (useful with repeated downloads):+.IP+.EX+source Checking1*.csv+.EE+.PP+See also \[dq]Working with CSV > Reading files specified by rule\[dq].+.SS \f[CR]separator\f[R]+You can use the \f[CR]separator\f[R] rule to read other kinds of+character\-separated data.+The argument is any single separator character, or the words+\f[CR]tab\f[R] or \f[CR]space\f[R] (case insensitive).+Eg, for comma\-separated values (CSV):+.IP+.EX+separator ,+.EE+.PP+or for semicolon\-separated values (SSV):+.IP+.EX+separator ;+.EE+.PP+or for tab\-separated values (TSV):+.IP+.EX+separator TAB+.EE+.PP+If the input file has a \f[CR].csv\f[R], \f[CR].ssv\f[R] or+\f[CR].tsv\f[R] file extension (or a \f[CR]csv:\f[R], \f[CR]ssv:\f[R],+\f[CR]tsv:\f[R] prefix), the appropriate separator will be inferred+automatically, and you won\[aq]t need this rule.+.SS \f[CR]skip\f[R]+.IP+.EX+skip N+.EE+.PP+The word \f[CR]skip\f[R] 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\[aq]ll need this whenever your CSV data contains header lines.+Note, empty and blank lines are skipped automatically, so you don\[aq]t+need to count those.+.PP+\f[CR]skip\f[R] 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.+.SS \f[CR]date\-format\f[R]+.IP+.EX+date\-format DATEFMT+.EE+.PP+This is a helper for the \f[CR]date\f[R] (and \f[CR]date2\f[R]) fields.+If your CSV dates are not formatted like \f[CR]YYYY\-MM\-DD\f[R],+\f[CR]YYYY/MM/DD\f[R] or \f[CR]YYYY.MM.DD\f[R], you\[aq]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:+.IP+.EX+# MM/DD/YY+date\-format %m/%d/%y+.EE+.IP+.EX+# D/M/YYYY+# The \- makes leading zeros optional.+date\-format %\-d/%\-m/%Y+.EE+.IP+.EX+# YYYY\-Mmm\-DD+date\-format %Y\-%h\-%d+.EE+.IP+.EX+# 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+.EE+.SS \f[CR]timezone\f[R]+.IP+.EX+timezone TIMEZONE+.EE+.PP+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\[aq]s native time zone, which helps+prevent off\-by\-one dates.+.PP+When the CSV date\-times do contain time zone information, you don\[aq]t+need this rule; instead, use \f[CR]%Z\f[R] in \f[CR]date\-format\f[R]+(or \f[CR]%z\f[R], \f[CR]%EZ\f[R], \f[CR]%Ez\f[R]; see the formatTime+link above).+.PP+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:+.IP+.EX+$ TZ=\-1000 hledger print \-f foo.csv  # or TZ=\-1000 hledger import foo.csv+.EE+.PP+\f[CR]timezone\f[R] currently does not understand timezone names, except+\[dq]UTC\[dq], \[dq]GMT\[dq], \[dq]EST\[dq], \[dq]EDT\[dq],+\[dq]CST\[dq], \[dq]CDT\[dq], \[dq]MST\[dq], \[dq]MDT\[dq],+\[dq]PST\[dq], or \[dq]PDT\[dq].+For others, use numeric format: +HHMM or \-HHMM.+.SS \f[CR]newest\-first\f[R]+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\[aq]s records are normally newest first, like:+.IP+.EX+2022\-10\-01, txn 3...+2022\-10\-01, txn 2...+2022\-10\-01, txn 1...+.EE+.PP+you can add the \f[CR]newest\-first\f[R] rule to help hledger generate+the transactions in correct order.+.IP+.EX+# same\-day CSV records are newest first+newest\-first+.EE+.SS \f[CR]intra\-day\-reversed\f[R]+If CSV records within a single day are ordered opposite to the overall+record order, you can add the \f[CR]intra\-day\-reversed\f[R] rule to+improve the order of journal entries.+Eg, here the overall record order is newest first, but same\-day records+are oldest first:+.IP+.EX+2022\-10\-02, txn 3...+2022\-10\-02, txn 4...+2022\-10\-01, txn 1...+2022\-10\-01, txn 2...+.EE+.IP+.EX+# transactions within each day are reversed with respect to the overall date order+intra\-day\-reversed+.EE+.SS \f[CR]decimal\-mark\f[R]+.IP+.EX+decimal\-mark .+.EE+.PP+or:+.IP+.EX+decimal\-mark ,+.EE+.PP+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.+.SS \f[CR]fields\f[R] list+.IP+.EX+fields FIELDNAME1, FIELDNAME2, ...+.EE+.PP+A fields list (the word \f[CR]fields\f[R] followed by comma\-separated+field names) is optional, but convenient.+It does two things:+.IP "1." 3+It names the CSV field in each column.+This can be convenient if you are referencing them in other rules, so+you can say \f[CR]%SomeField\f[R] instead of remembering \f[CR]%13\f[R].+.IP "2." 3+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\[aq]s fields and build a+transaction.+.PP+Here\[aq]s an example that says \[dq]use the 1st, 2nd and 4th fields as+the transaction\[aq]s date, description and amount; name the last two+fields for later reference; and ignore the others\[dq]:+.IP+.EX+fields date, description, , amount, , , somefield, anotherfield+.EE+.PP+In a fields list, the separator is always comma; it is unrelated to the+CSV file\[aq]s separator.+Also:+.IP \[bu] 2+There must be least two items in the list (at least one comma).+.IP \[bu] 2+Field names may not contain spaces.+Spaces before/after field names are optional.+.IP \[bu] 2+Field names may contain \f[CR]_\f[R] (underscore) or \f[CR]\-\f[R]+(hyphen).+.IP \[bu] 2+Fields you don\[aq]t care about can be given a dummy name or an empty+name.+.PP+If the CSV contains column headings, it\[aq]s convenient to use these+for your field names, suitably modified (eg lower\-cased with spaces+replaced by underscores).+.PP+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\[aq]s \[dq]balance\[dq] field+\f[CR]balance_\f[R] to avoid directly setting hledger\[aq]s+\f[CR]balance\f[R] field (and generating a balance assertion).+.SS Field assignment+.IP+.EX+HLEDGERFIELD FIELDVALUE+.EE+.PP+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).+.PP+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 (\f[CR]%N\f[R]) or by the name they+were given in the fields list (\f[CR]%CSVFIELD\f[R]), and regular+expression match groups (\f[CR]\[rs]N\f[R]).+.PP+Some examples:+.IP+.EX+# set the amount to the 4th CSV field, with \[dq] USD\[dq] appended+amount %4 USD++# combine three fields to make a comment, containing note: and date: tags+comment note: %somefield \- %anotherfield, date: %1+.EE+.PP+Tips:+.IP \[bu] 2+Interpolation strips outer whitespace (so a CSV value like+\f[CR]\[dq] 1 \[dq]\f[R] becomes \f[CR]1\f[R] when interpolated)+(#1051).+.IP \[bu] 2+Interpolations always refer to a CSV field \- you can\[aq]t interpolate+a hledger field.+(See Referencing other fields below).+.SS Field names+Note the two kinds of field names mentioned here, and used only in+hledger CSV rules files:+.IP "1." 3+\f[B]CSV field names\f[R] (\f[CR]CSVFIELD\f[R] in these docs): you can+optionally name the CSV columns for easy reference (since hledger+doesn\[aq]t yet automatically recognise column headings in a CSV file),+by writing arbitrary names in a \f[CR]fields\f[R] list, eg:+.RS 4+.IP+.EX+fields When, What, Some_Id, Net, Total, Foo, Bar+.EE+.RE+.IP "2." 3+Special \f[B]hledger field names\f[R] (\f[CR]HLEDGERFIELD\f[R] 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:+.RS 4+.IP+.EX+date        %When+code        %Some_Id+description %What+comment     %Foo %Bar+amount1     $ %Total+.EE+.PP+or directly in a \f[CR]fields\f[R] list:+.IP+.EX+fields date, description, code, , amount1, Foo, Bar+currency $+comment  %Foo %Bar+.EE+.RE+.PP+Here are all the special hledger field names available, and what happens+when you assign values to them:+.SS date field+Assigning to \f[CR]date\f[R] sets the transaction date.+.SS date2 field+\f[CR]date2\f[R] sets the transaction\[aq]s secondary date, if any.+.SS status field+\f[CR]status\f[R] sets the transaction\[aq]s status, if any.+.SS code field+\f[CR]code\f[R] sets the transaction\[aq]s code, if any.+.SS description field+\f[CR]description\f[R] sets the transaction\[aq]s description, if any.+.SS comment field+\f[CR]comment\f[R] sets the transaction\[aq]s comment, if any.+.PP+\f[CR]commentN\f[R], where N is a number, sets the Nth posting\[aq]s+comment.+.PP+You can assign multi\-line comments by writing literal \f[CR]\[rs]n\f[R]+in the code.+A comment starting with \f[CR]\[rs]n\f[R] will begin on a new line.+.PP+Comments can contain tags, as usual.+.SS account field+Assigning to \f[CR]accountN\f[R], where N is 1 to 99, sets the account+name of the Nth posting, and causes that posting to be generated.+.PP+Most often there are two postings, so you\[aq]ll want to set+\f[CR]account1\f[R] and \f[CR]account2\f[R].+Typically \f[CR]account1\f[R] is associated with the CSV file, and is+set once with a top\-level assignment, while \f[CR]account2\f[R] is set+based on each transaction\[aq]s description, in conditional rules.+.PP+If a posting\[aq]s account name is left unset but its amount is set (see+below), a default account name will be chosen (like+\[dq]expenses:unknown\[dq] or \[dq]income:unknown\[dq]).+.SS amount field+There are several ways to set posting amounts from CSV, useful in+different situations.+.IP "1." 3+\f[B]\f[CB]amount\f[B]\f[R] 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.+.IP "2." 3+\f[B]\f[CB]amount\-in\f[B]\f[R] and \f[B]\f[CB]amount\-out\f[B]\f[R]+work exactly like the above, but should be used when the CSV has two+amount fields (such as \[dq]Debit\[dq] and \[dq]Credit\[dq], or+\[dq]Inflow\[dq] and \[dq]Outflow\[dq]).+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:+.RS 4+.IP \[bu] 2+It\[aq]s not \[dq]amount\-in for posting 1 and amount\-out for posting+2\[dq], it is \[dq]extract a single amount from the amount\-in or+amount\-out field, and use that for posting 1 and (negated) for posting+2\[dq].+.IP \[bu] 2+Don\[aq]t use both \f[CR]amount\f[R] and+\f[CR]amount\-in\f[R]/\f[CR]amount\-out\f[R] in the same rules file;+choose based on whether the amount is in a single CSV field or spread+across two fields.+.IP \[bu] 2+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.+.IP \[bu] 2+hledger assumes both CSV fields contain unsigned numbers, and it+automatically negates the amount\-out values.+.IP \[bu] 2+If the data doesn\[aq]t fit these requirements, you\[aq]ll probably need+an if rule (see below).+.RE+.IP "3." 3+\f[B]\f[CB]amountN\f[B]\f[R] (where N is a number from 1 to 99) sets the+amount of only a single posting: the Nth posting in the transaction.+You\[aq]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\[aq]t have to be consecutive; with if rules,+higher posting numbers can be useful to ensure a certain order of+postings.+.IP "4." 3+\f[B]\f[CB]amountN\-in\f[B]\f[R] and \f[B]\f[CB]amountN\-out\f[B]\f[R]+work exactly like the above, but should be used when the CSV has two+amount fields.+This is analogous to \f[CR]amount\-in\f[R] and \f[CR]amount\-out\f[R],+and those tips also apply here.+.IP "5." 3+Remember that a \f[CR]fields\f[R] list can also do assignments.+So in a fields list if you name a CSV field \[dq]amount\[dq], that+counts as assigning to \f[CR]amount\f[R].+(If you don\[aq]t want that, call it something else in the fields list,+like \[dq]amount_\[dq].)+.IP "6." 3+The above don\[aq]t handle every situation; if you need more+flexibility, use an \f[CR]if\f[R] rule to set amounts conditionally.+See \[dq]Working with CSV > Setting amounts\[dq] below for more on this+and on amount\-setting generally.+.SS currency field+\f[CR]currency\f[R] sets a currency symbol, to be prepended to all+postings\[aq] amounts.+You can use this if the CSV amounts do not have a currency symbol, eg if+it is in a separate column.+.PP+\f[CR]currencyN\f[R] prepends a currency symbol to just the Nth+posting\[aq]s amount.+.SS balance field+\f[CR]balanceN\f[R] sets a balance assertion amount (or if the posting+amount is left empty, a balance assignment) on posting N.+.PP+\f[CR]balance\f[R] is a compatibility spelling for hledger <1.17; it is+equivalent to \f[CR]balance1\f[R].+.PP+You can adjust the type of assertion/assignment with the+\f[CR]balance\-type\f[R] rule (see below).+.PP+See the Working with CSV tips below for more about setting amounts and+currency.+.SS \f[CR]if\f[R] 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: \[dq]if blocks\[dq],+described here, and \[dq]if tables\[dq], described below.+.PP+An if block is the word \f[CR]if\f[R] and one or more \[dq]matcher\[dq]+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,+.IP+.EX+if MATCHER+ RULE+.EE+.PP+or+.IP+.EX+if+MATCHER+MATCHER+MATCHER+ RULE+ RULE+.EE+.PP+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:+.IP \[bu] 2+\f[CR]skip\f[R] \- skips the matched CSV record (generating no+transaction from it)+.IP \[bu] 2+\f[CR]end\f[R] \- skips the rest of the current CSV file.+.PP+Some examples:+.IP+.EX+# if the record contains \[dq]groceries\[dq], set account2 to \[dq]expenses:groceries\[dq]+if groceries+ account2 expenses:groceries+.EE+.IP+.EX+# 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+.EE+.IP+.EX+# if an empty record is seen (assuming five fields), ignore the rest of the CSV file+if ,,,,+ end+.EE+.SS Matchers+There are two kinds:+.IP "1." 3+A record matcher is a word or single\-line text fragment or regular+expression (\f[CR]REGEX\f[R]), which hledger will try to match+case\-insensitively anywhere within the CSV record.+.PD 0+.P+.PD+Eg: \f[CR]whole foods\f[R]+.IP "2." 3+A field matcher is preceded with a percent sign and CSV field name+(\f[CR]%CSVFIELD REGEX\f[R]).+hledger will try to match these just within the named CSV field.+.PD 0+.P+.PD+Eg: \f[CR]%date 2023\f[R]+.PP+The regular expression is (as usual in hledger) a POSIX extended regular+expression, that also supports GNU word boundaries (\f[CR]\[rs]b\f[R],+\f[CR]\[rs]B\f[R], \f[CR]\[rs]<\f[R], \f[CR]\[rs]>\f[R]), and nothing+else.+If you have trouble, see \[dq]Regular expressions\[dq] in the hledger+manual (https://hledger.org/hledger.html#regular\-expressions).+.SS What matchers match+With record matchers, it\[aq]s important to know that the record matched+is not the original CSV record, but a modified one: separators will be+converted to commas, and enclosing double quotes (but not enclosing+whitespace) are removed.+So for example, when reading an SSV file, if the original record was:+.IP+.EX+2023\-01\-01; \[dq]Acme, Inc.\[dq];  1,000+.EE+.PP+the regex would see, and try to match, this modified record text:+.IP+.EX+2023\-01\-01,Acme, Inc.,  1,000+.EE+.SS Combining matchers+When an if block has multiple matchers, they are combined as follows:+.IP \[bu] 2+By default they are OR\[aq]d (any of them can match)+.IP \[bu] 2+When a matcher is preceded by ampersand (\f[CR]&\f[R], at the start of+the line) it will be AND\[aq]ed with the previous matcher (all in the+AND\[aq]ed group must match)+.IP \[bu] 2+\f[I]Added in 1.32\f[R] When a matcher is preceded by an exclamation+mark (\f[CR]!\f[R]), it is negated (it must not match).+.PP+Note currently there is a limitation: you can\[aq]t use both+\f[CR]&\f[R] and \f[CR]!\f[R] on the same line (you can\[aq]t AND a+negated matcher).+.SS Match groups+\f[I]Added in 1.32\f[R]+.PP+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 (\f[CR](\f[R] and+\f[CR])\f[R]) and can be nested.+Each group is available in field assignments using the token+\f[CR]\[rs]N\f[R], where N is an index into the match groups for this+conditional block (e.g.+\f[CR]\[rs]1\f[R], \f[CR]\[rs]2\f[R], etc.).+.PP+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:+.IP+.EX+if %date (....\-..)\-..+  comment2 date:\[rs]1\-01+.EE+.PP+Another example: Read the expense account from the CSV field, but throw+away a prefix:+.IP+.EX+if %account1 liabilities:family:(expenses:.*)+    account1 \[rs]1+.EE+.SS \f[CR]if\f[R] table+\[dq]if tables\[dq] are an alternative to if blocks; they can express+many matchers and field assignments in a more compact tabular format,+like this:+.IP+.EX+if,HLEDGERFIELD1,HLEDGERFIELD2,...+MATCHERA,VALUE1,VALUE2,...+MATCHERB,VALUE1,VALUE2,...+; Comment line that explains MATCHERC+MATCHERC,VALUE1,VALUE2,...+<empty line>+.EE+.PP+The first character after \f[CR]if\f[R] is taken to be this if+table\[aq]s field separator.+It is unrelated to the separator used in the CSV file.+It should be a non\-alphanumeric character like \f[CR],\f[R] or+\f[CR]|\f[R] 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).+.PP+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).+.PP+An if table like the above is interpreted as follows: try all of the+matchers; whenever a matcher succeeds, assign all of the values on that+line to the corresponding hledger fields; If multiple lines match, later+lines will override fields assigned by the earlier ones \- just like the+sequence of \f[CR]if\f[R] blocks would behave.+.PP+If table presented above is equivalent to this sequence of if blocks:+.IP+.EX+if MATCHERA+  HLEDGERFIELD1 VALUE1+  HLEDGERFIELD2 VALUE2+  ...++if MATCHERB+  HLEDGERFIELD1 VALUE1+  HLEDGERFIELD2 VALUE2+  ...++; Comment line which explains MATCHERC+if MATCHERC+  HLEDGERFIELD1 VALUE1+  HLEDGERFIELD2 VALUE2+  ...+.EE+.PP+Example:+.IP+.EX+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+.EE+.SS \f[CR]balance\-type\f[R]+Balance assertions generated by assigning to balanceN are of the simple+\f[CR]=\f[R] 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+\f[CR]balance\-type\f[R] rule:+.IP+.EX+# balance assertions will consider all commodities and all subaccounts+balance\-type ==*+.EE+.PP+Here are the balance assertion types for quick reference:+.IP+.EX+=    single commodity, exclude subaccounts+=*   single commodity, include subaccounts+==   multi commodity,  exclude subaccounts+==*  multi commodity,  include subaccounts+.EE+.SS \f[CR]include\f[R]+.IP+.EX+include RULESFILE+.EE+.PP+This includes the contents of another CSV rules file at this point.+\f[CR]RULESFILE\f[R] is an absolute file path or a path relative to the+current file\[aq]s directory.+This can be useful for sharing common rules between several rules files,+eg:+.IP+.EX+# someaccount.csv.rules++## someaccount\-specific rules+fields   date,description,amount+account1 assets:someaccount+account2 expenses:misc++## common rules+include categorisation.rules+.EE+.SS Working with CSV+Some tips:+.SS Rapid feedback+It\[aq]s a good idea to get rapid feedback while+creating/troubleshooting CSV rules.+Here\[aq]s a good way, using entr from eradman.com/entrproject:+.IP+.EX+$ ls foo.csv* | entr bash \-c \[aq]echo \-\-\-\-; hledger \-f foo.csv print desc:SOMEDESC\[aq]+.EE+.PP+A desc: query (eg) is used to select just one, or a few, transactions of+interest.+\[dq]bash \-c\[dq] 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.+.SS 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:+.IP \[bu] 2+Values may be enclosed in double quotes, or not.+Enclosing in single quotes is not allowed.+(Eg \f[CR]\[aq]A\[aq],\[aq]B\[aq]\f[R] is rejected.)+.IP \[bu] 2+When values are enclosed in double quotes, spaces outside the quotes are+not allowed.+(Eg \f[CR]\[dq]A\[dq], \[dq]B\[dq]\f[R] is rejected.)+.IP \[bu] 2+When values are not enclosed in quotes, they may not contain double+quotes.+(Eg \f[CR]A\[dq]A, B\f[R] is rejected.)+.PP+If your CSV/SSV/TSV is not valid in this sense, you\[aq]ll need to+transform it before reading with hledger.+Try using sed, or a more permissive CSV parser like python\[aq]s csv+lib.+.SS 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\[aq]s best if CSV/SSV/TSV files are named with a \f[CR].csv\f[R],+\f[CR].ssv\f[R] or \f[CR].tsv\f[R] filename extension.+(More about this at Data formats.)+.PP+When reading files with the \[dq]wrong\[dq] extension, you can ensure+the CSV reader (and the default field separator) by prefixing the file+path with \f[CR]csv:\f[R], \f[CR]ssv:\f[R] or \f[CR]tsv:\f[R]: Eg:+.IP+.EX+$ hledger \-f ssv:foo.dat print+.EE+.PP+You can also override the default field separator with a separator rule+if needed.+.SS Reading CSV from standard input+You\[aq]ll need the file format prefix when reading CSV from stdin also,+since hledger assumes journal format by default.+Eg:+.IP+.EX+$ cat foo.dat | hledger \-f ssv:\- print+.EE+.SS Reading multiple CSV files+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.+.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].+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\[aq]s download directory.+.PP+This feature was added in hledger 1.30, so you won\[aq]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\[aq]s default CSV filenames are+different and can be recognised by a glob pattern.+So you can put a rule like \f[CR]source Checking1*.csv\f[R] in+foo\-checking.csv.rules, and then periodically follow a workflow like:+.IP "1." 3+Download CSV from Foo\[aq]s website, using your browser\[aq]s defaults+.IP "2." 3+Run \f[CR]hledger import foo\-checking.csv.rules\f[R] to import any new+transactions+.PP+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 \f[CR]*\f[R]+wild card and because it is the most recent.+.SS 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.+.PP+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:+.IP+.EX+$ hledger \-f file.csv print | hledger \-f\- print+.EE+.SS 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.+.PP+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\[aq]t have to remember how many times you+ran it or with which version of the CSV.+(It keeps state in a hidden \f[CR].latest.FILE.csv\f[R] file.)+This is the easiest way to import CSV data.+Eg:+.IP+.EX+# download the latest CSV files, then run this command.+# Note, no \-f flags needed here.+$ hledger import *.csv [\-\-dry]+.EE+.PP+This method works for most CSV files.+(Where records have a stable chronological order, and new records appear+only at the new end.)+.PP+A number of other tools and workflows, hledger\-specific and otherwise,+exist for converting, deduplicating, classifying and managing CSV data.+See:+.IP \[bu] 2+https://hledger.org/cookbook.html#setups\-and\-workflows+.IP \[bu] 2+https://plaintextaccounting.org \-> data import/conversion+.SS Setting amounts+Continuing from amount field above, here are more tips for+amount\-setting:+.IP "1." 3+\f[B]If the amount is in a single CSV field:\f[R]+.PD 0+.P+.PD+.RS 4+.IP "a." 3+\f[B]If its sign indicates direction of flow:\f[R]+.PD 0+.P+.PD+Assign it to \f[CR]amountN\f[R], to set the Nth posting\[aq]s amount.+N is usually 1 or 2 but can go up to 99.+.IP "b." 3+\f[B]If another field indicates direction of flow:\f[R]+.PD 0+.P+.PD+Use one or more conditional rules to set the appropriate amount sign.+Eg:+.IP+.EX+# assume a withdrawal unless Type contains \[dq]deposit\[dq]:+amount1  \-%Amount+if %Type deposit+  amount1  %Amount+.EE+.RE+.IP "2." 3+\f[B]If the amount is in two CSV fields (such as Debit and Credit, or In+and Out):\f[R]+.PD 0+.P+.PD+.RS 4+.IP "a." 3+\f[B]If both fields are unsigned:\f[R]+.PD 0+.P+.PD+Assign one field to \f[CR]amountN\-in\f[R] and the other to+\f[CR]amountN\-out\f[R].+hledger will automatically negate the \[dq]out\[dq] field, and will use+whichever field value is non\-zero as posting N\[aq]s amount.+.IP "b." 3+\f[B]If either field is signed:\f[R]+.PD 0+.P+.PD+You will probably need to override hledger\[aq]s sign for one or the+other field, as in the following example:+.IP+.EX+# 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+.EE+.IP "c." 3+\f[B]If both fields can contain a non\-zero value (or both can be+empty):\f[R]+.PD 0+.P+.PD+The \-in/\-out rules normally choose the value which is+non\-zero/non\-empty.+Some value pairs can be ambiguous, such as \f[CR]1\f[R] and+\f[CR]none\f[R].+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:+.IP+.EX+fields date, description, in, out+if %in [1\-9]+ amount1 %in+if %out [1\-9]+ amount1 %out+.EE+.RE+.IP "3." 3+\f[B]If you want posting 2\[aq]s amount converted to cost:\f[R]+.PD 0+.P+.PD+Use the unnumbered \f[CR]amount\f[R] (or \f[CR]amount\-in\f[R] and+\f[CR]amount\-out\f[R]) syntax.+.IP "4." 3+\f[B]If the CSV has only balance amounts, not transaction amounts:\f[R]+.PD 0+.P+.PD+Assign to \f[CR]balanceN\f[R], to set a balance assignment on the Nth+posting, causing the posting\[aq]s amount to be calculated+automatically.+\f[CR]balance\f[R] with no number is equivalent to \f[CR]balance1\f[R].+In this situation hledger is more likely to guess the wrong default+account name, so you may need to set that explicitly.+.SS 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+\f[CR]amount1  AMT \[at] COST\f[R]):+.IP \[bu] 2+\f[B]If an amount value begins with a plus sign:\f[R]+.PD 0+.P+.PD+that will be removed: \f[CR]+AMT\f[R] becomes \f[CR]AMT\f[R]+.IP \[bu] 2+\f[B]If an amount value is parenthesised:\f[R]+.PD 0+.P+.PD+it will be de\-parenthesised and sign\-flipped: \f[CR](AMT)\f[R] becomes+\f[CR]\-AMT\f[R]+.IP \[bu] 2+\f[B]If an amount value has two minus signs (or two sets of parentheses,+or a minus sign and parentheses):\f[R]+.PD 0+.P+.PD+they cancel out and will be removed: \f[CR]\-\-AMT\f[R] or+\f[CR]\-(AMT)\f[R] becomes \f[CR]AMT\f[R]+.IP \[bu] 2+\f[B]If an amount value contains just a sign (or just a set of+parentheses):\f[R]+.PD 0+.P+.PD+that is removed, making it an empty value.+\f[CR]\[dq]+\[dq]\f[R] or \f[CR]\[dq]\-\[dq]\f[R] or+\f[CR]\[dq]()\[dq]\f[R] becomes \f[CR]\[dq]\[dq]\f[R].+.PP+It\[aq]s not possible (without preprocessing the CSV) to set an amount+to its absolute value, ie discard its sign.+.SS Setting currency/commodity+If the currency/commodity symbol is included in the CSV\[aq]s amount+field(s):+.IP+.EX+2023\-01\-01,foo,$123.00+.EE+.PP+you don\[aq]t have to do anything special for the commodity symbol, it+will be assigned as part of the amount.+Eg:+.IP+.EX+fields date,description,amount+.EE+.IP+.EX+2023\-01\-01 foo+    expenses:unknown         $123.00+    income:unknown          $\-123.00+.EE+.PP+If the currency is provided as a separate CSV field:+.IP+.EX+2023\-01\-01,foo,USD,123.00+.EE+.PP+You can assign that to the \f[CR]currency\f[R] pseudo\-field, which has+the special effect of prepending itself to every amount in the+transaction (on the left, with no separating space):+.IP+.EX+fields date,description,currency,amount+.EE+.IP+.EX+2023\-01\-01 foo+    expenses:unknown       USD123.00+    income:unknown        USD\-123.00+.EE+.PP+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:+.IP+.EX+fields date,description,cur,amt+amount %amt %cur+.EE+.IP+.EX+2023\-01\-01 foo+    expenses:unknown        123.00 USD+    income:unknown         \-123.00 USD+.EE+.PP+Note we used a temporary field name (\f[CR]cur\f[R]) that is not+\f[CR]currency\f[R] \- that would trigger the prepending effect, which+we don\[aq]t want here.+.SS Amount decimal places+When you are reading CSV data, eg with a command like+\f[CR]hledger \-f foo.csv print\f[R], hledger will infer each+commodity\[aq]s decimal precision (and other commodity display styles)+from the amounts \- much as when reading a journal file without+\f[CR]commodity\f[R] directives (see the link).+.PP+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.+.PP+When you are importing CSV data with the \f[CR]import\f[R] command, eg+\f[CR]hledger import foo.csv\f[R], there\[aq]s another step:+\f[CR]import\f[R] tries to make the new entries conform to the+journal\[aq]s existing styles.+So for each commodity \- let\[aq]s say it\[aq]s EUR \- \f[CR]import\f[R]+will choose:+.IP "1." 3+the style declared for EUR by a \f[CR]commodity\f[R] directive in the+journal+.IP "2." 3+otherwise, the style inferred from EUR amounts in the journal+.IP "3." 3+otherwise, the style inferred from EUR amounts generated by the CSV+rules.+.PP+TLDR: if \f[CR]import\f[R] is not generating the precisions or styles+you want, add a \f[CR]commodity\f[R] directive to specify them.+.SS Referencing other fields+In field assignments, you can interpolate only CSV fields, not hledger+fields.+In the example below, there\[aq]s both a CSV field and a hledger field+named amount1, but %amount1 always means the CSV field, not the hledger+field:+.IP+.EX+# Name the third CSV field \[dq]amount1\[dq]+fields date,description,amount1++# Set hledger\[aq]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+.EE+.PP+Here, since there\[aq]s no CSV amount1 field, %amount1 will produce a+literal \[dq]amount1\[dq]:+.IP+.EX+fields date,description,csvamount+amount1 %csvamount USD+# Can\[aq]t interpolate amount1 here+comment %amount1+.EE+.PP+When there are multiple field assignments to the same hledger field,+only the last one takes effect.+Here, comment\[aq]s value will be be B, or C if \[dq]something\[dq] is+matched, but never A:+.IP+.EX+comment A+comment B+if something+ comment C+.EE+.SS How CSV rules are evaluated+Here\[aq]s how to think of CSV rules being evaluated (if you really need+to).+First,+.IP \[bu] 2+\f[CR]include\f[R] \- 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.)+.PP+Then \[dq]global\[dq] rules are evaluated, top to bottom.+If a rule is repeated, the last one wins:+.IP \[bu] 2+\f[CR]skip\f[R] (at top level)+.IP \[bu] 2+\f[CR]date\-format\f[R]+.IP \[bu] 2+\f[CR]newest\-first\f[R]+.IP \[bu] 2+\f[CR]fields\f[R] \- names the CSV fields, optionally sets up initial+assignments to hledger fields+.PP+Then for each CSV record in turn:+.IP \[bu] 2+test all \f[CR]if\f[R] blocks.+If any of them contain a \f[CR]end\f[R] rule, skip all remaining CSV+records.+Otherwise if any of them contain a \f[CR]skip\f[R] rule, skip that many+CSV records.+If there are multiple matched \f[CR]skip\f[R] rules, the first one wins.+.IP \[bu] 2+collect all field assignments at top level and in matched \f[CR]if\f[R]+blocks.+When there are multiple assignments for a field, keep only the last one.+.IP \[bu] 2+compute a value for each hledger field \- either the one that was+assigned to it (and interpolate the %CSVFIELD references), or a default+.IP \[bu] 2+generate a hledger transaction (journal entry) from these values.+.PP+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.+.PP+.SS Well factored rules+Some things than can help reduce duplication and complexity in rules+files:+.IP \[bu] 2+Extracting common rules usable with multiple CSV files into a+\f[CR]common.rules\f[R], and adding \f[CR]include common.rules\f[R] to+each CSV\[aq]s rules file.+.IP \[bu] 2+Splitting if blocks into smaller if blocks, extracting the frequently+used parts.+.SS CSV rules examples+.SS Bank of Ireland+Here\[aq]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:+.IP+.EX+Date,Details,Debit,Credit,Balance+07/12/2012,LODGMENT       529898,,10.0,131.21+07/12/2012,PAYMENT,5,,126+.EE+.IP+.EX+# 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 \[dq]balance\[dq]+# 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+.EE+.IP+.EX+$ 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+.EE+.PP+The balance assertions don\[aq]t raise an error above, because we\[aq]re+reading directly from CSV, but they will be checked if these entries are+imported into a journal file.+.SS Coinbase+A simple example with some CSV from Coinbase.+The spot price is recorded using cost notation.+The legacy \f[CR]amount\f[R] field name conveniently sets amount 2+(posting 2\[aq]s amount) to the total cost.+.IP+.EX+# 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,\[dq]\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]Received 100.00 USDC from an external account\[dq]+.EE+.IP+.EX+# 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 \[at] %Spot_Price_at_Transaction %Spot_Price_Currency+.EE+.IP+.EX+$ hledger print \-f coinbase.csv+2021\-12\-30 Received 100.00 USDC from an external account+    assets:coinbase:cc    100 USDC \[at] 0.740000 GBP+    income:unknown                 \-74.000000 GBP+.EE+.SS Amazon+Here we convert amazon.com order history, and use an if block to+generate a third posting if there\[aq]s a fee.+(In practice you\[aq]d probably get this data from your bank instead,+but it\[aq]s an example.)+.IP+.EX+\[dq]Date\[dq],\[dq]Type\[dq],\[dq]To/From\[dq],\[dq]Name\[dq],\[dq]Status\[dq],\[dq]Amount\[dq],\[dq]Fees\[dq],\[dq]Transaction ID\[dq]+\[dq]Jul 29, 2012\[dq],\[dq]Payment\[dq],\[dq]To\[dq],\[dq]Foo.\[dq],\[dq]Completed\[dq],\[dq]$20.00\[dq],\[dq]$0.00\[dq],\[dq]16000000000000DGLNJPI1P9B8DKPVHL\[dq]+\[dq]Jul 30, 2012\[dq],\[dq]Payment\[dq],\[dq]To\[dq],\[dq]Adapteva, Inc.\[dq],\[dq]Completed\[dq],\[dq]$25.00\[dq],\[dq]$1.00\[dq],\[dq]17LA58JSKRD4HDGLNJPI1P9B8DKPVHL\[dq]+.EE+.IP+.EX+# amazon\-orders.csv.rules++# skip one header line+skip 1++# name the csv fields, and assign the transaction\[aq]s date, amount and code.+# Avoided the \[dq]status\[dq] and \[dq]amount\[dq] 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\[aq]m assuming amzamount excludes the fees, don\[aq]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+.EE+.IP+.EX+$ 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+.EE+.SS Paypal+Here\[aq]s a real\-world rules file for (customised) Paypal CSV, with+some Paypal\-specific rules, and a second rules file included:+.IP+.EX+\[dq]Date\[dq],\[dq]Time\[dq],\[dq]TimeZone\[dq],\[dq]Name\[dq],\[dq]Type\[dq],\[dq]Status\[dq],\[dq]Currency\[dq],\[dq]Gross\[dq],\[dq]Fee\[dq],\[dq]Net\[dq],\[dq]From Email Address\[dq],\[dq]To Email Address\[dq],\[dq]Transaction ID\[dq],\[dq]Item Title\[dq],\[dq]Item ID\[dq],\[dq]Reference Txn ID\[dq],\[dq]Receipt ID\[dq],\[dq]Balance\[dq],\[dq]Note\[dq]+\[dq]10/01/2019\[dq],\[dq]03:46:20\[dq],\[dq]PDT\[dq],\[dq]Calm Radio\[dq],\[dq]Subscription Payment\[dq],\[dq]Completed\[dq],\[dq]USD\[dq],\[dq]\-6.99\[dq],\[dq]0.00\[dq],\[dq]\-6.99\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]memberships\[at]calmradio.com\[dq],\[dq]60P57143A8206782E\[dq],\[dq]MONTHLY \- $1 for the first 2 Months: Me \- Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month\[dq],\[dq]\[dq],\[dq]I\-R8YLY094FJYR\[dq],\[dq]\[dq],\[dq]\-6.99\[dq],\[dq]\[dq]+\[dq]10/01/2019\[dq],\[dq]03:46:20\[dq],\[dq]PDT\[dq],\[dq]\[dq],\[dq]Bank Deposit to PP Account \[dq],\[dq]Pending\[dq],\[dq]USD\[dq],\[dq]6.99\[dq],\[dq]0.00\[dq],\[dq]6.99\[dq],\[dq]\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]0TU1544T080463733\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]60P57143A8206782E\[dq],\[dq]\[dq],\[dq]0.00\[dq],\[dq]\[dq]+\[dq]10/01/2019\[dq],\[dq]08:57:01\[dq],\[dq]PDT\[dq],\[dq]Patreon\[dq],\[dq]PreApproved Payment Bill User Payment\[dq],\[dq]Completed\[dq],\[dq]USD\[dq],\[dq]\-7.00\[dq],\[dq]0.00\[dq],\[dq]\-7.00\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]support\[at]patreon.com\[dq],\[dq]2722394R5F586712G\[dq],\[dq]Patreon* Membership\[dq],\[dq]\[dq],\[dq]B\-0PG93074E7M86381M\[dq],\[dq]\[dq],\[dq]\-7.00\[dq],\[dq]\[dq]+\[dq]10/01/2019\[dq],\[dq]08:57:01\[dq],\[dq]PDT\[dq],\[dq]\[dq],\[dq]Bank Deposit to PP Account \[dq],\[dq]Pending\[dq],\[dq]USD\[dq],\[dq]7.00\[dq],\[dq]0.00\[dq],\[dq]7.00\[dq],\[dq]\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]71854087RG994194F\[dq],\[dq]Patreon* Membership\[dq],\[dq]\[dq],\[dq]2722394R5F586712G\[dq],\[dq]\[dq],\[dq]0.00\[dq],\[dq]\[dq]+\[dq]10/19/2019\[dq],\[dq]03:02:12\[dq],\[dq]PDT\[dq],\[dq]Wikimedia Foundation, Inc.\[dq],\[dq]Subscription Payment\[dq],\[dq]Completed\[dq],\[dq]USD\[dq],\[dq]\-2.00\[dq],\[dq]0.00\[dq],\[dq]\-2.00\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]tle\[at]wikimedia.org\[dq],\[dq]K9U43044RY432050M\[dq],\[dq]Monthly donation to the Wikimedia Foundation\[dq],\[dq]\[dq],\[dq]I\-R5C3YUS3285L\[dq],\[dq]\[dq],\[dq]\-2.00\[dq],\[dq]\[dq]+\[dq]10/19/2019\[dq],\[dq]03:02:12\[dq],\[dq]PDT\[dq],\[dq]\[dq],\[dq]Bank Deposit to PP Account \[dq],\[dq]Pending\[dq],\[dq]USD\[dq],\[dq]2.00\[dq],\[dq]0.00\[dq],\[dq]2.00\[dq],\[dq]\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]3XJ107139A851061F\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]K9U43044RY432050M\[dq],\[dq]\[dq],\[dq]0.00\[dq],\[dq]\[dq]+\[dq]10/22/2019\[dq],\[dq]05:07:06\[dq],\[dq]PDT\[dq],\[dq]Noble Benefactor\[dq],\[dq]Subscription Payment\[dq],\[dq]Completed\[dq],\[dq]USD\[dq],\[dq]10.00\[dq],\[dq]\-0.59\[dq],\[dq]9.41\[dq],\[dq]noble\[at]bene.fac.tor\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]6L8L1662YP1334033\[dq],\[dq]Joyful Systems\[dq],\[dq]\[dq],\[dq]I\-KC9VBGY2GWDB\[dq],\[dq]\[dq],\[dq]9.41\[dq],\[dq]\[dq]+.EE+.IP+.EX+# paypal\-custom.csv.rules++# Tips:+# Export from Activity \-> Statements \-> Custom \-> Activity download+# Suggested transaction type: \[dq]Balance affecting\[dq]+# Paypal\[aq]s default fields in 2018 were:+# \[dq]Date\[dq],\[dq]Time\[dq],\[dq]TimeZone\[dq],\[dq]Name\[dq],\[dq]Type\[dq],\[dq]Status\[dq],\[dq]Currency\[dq],\[dq]Gross\[dq],\[dq]Fee\[dq],\[dq]Net\[dq],\[dq]From Email Address\[dq],\[dq]To Email Address\[dq],\[dq]Transaction ID\[dq],\[dq]Shipping Address\[dq],\[dq]Address Status\[dq],\[dq]Item Title\[dq],\[dq]Item ID\[dq],\[dq]Shipping and Handling Amount\[dq],\[dq]Insurance Amount\[dq],\[dq]Sales Tax\[dq],\[dq]Option 1 Name\[dq],\[dq]Option 1 Value\[dq],\[dq]Option 2 Name\[dq],\[dq]Option 2 Value\[dq],\[dq]Reference Txn ID\[dq],\[dq]Invoice Number\[dq],\[dq]Custom Number\[dq],\[dq]Quantity\[dq],\[dq]Receipt ID\[dq],\[dq]Balance\[dq],\[dq]Address Line 1\[dq],\[dq]Address Line 2/District/Neighborhood\[dq],\[dq]Town/City\[dq],\[dq]State/Province/Region/County/Territory/Prefecture/Republic\[dq],\[dq]Zip/Postal Code\[dq],\[dq]Country\[dq],\[dq]Contact Phone Number\[dq],\[dq]Subject\[dq],\[dq]Note\[dq],\[dq]Country Code\[dq],\[dq]Balance Impact\[dq]+# This rules file assumes the following more detailed fields, configured in \[dq]Customize report fields\[dq]:+# \[dq]Date\[dq],\[dq]Time\[dq],\[dq]TimeZone\[dq],\[dq]Name\[dq],\[dq]Type\[dq],\[dq]Status\[dq],\[dq]Currency\[dq],\[dq]Gross\[dq],\[dq]Fee\[dq],\[dq]Net\[dq],\[dq]From Email Address\[dq],\[dq]To Email Address\[dq],\[dq]Transaction ID\[dq],\[dq]Item Title\[dq],\[dq]Item ID\[dq],\[dq]Reference Txn ID\[dq],\[dq]Receipt ID\[dq],\[dq]Balance\[dq],\[dq]Note\[dq]++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\[aq]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\[aq]s income (a debit)+if %grossamount \[ha][\[ha]\-]+ account2 income:unknown+# if negative, it\[aq]s an expense (a credit)+if %grossamount \[ha]\-+ 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+.EE+.IP+.EX+# 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+.EE+.IP+.EX+$ 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\[at]joyful.com, toemail:memberships\[at]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\[at]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\[at]joyful.com, toemail:support\[at]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\[at]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\[at]joyful.com, toemail:tle\[at]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\[at]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\[at]bene.fac.tor, toemail:simon\[at]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:+.EE+.SH Timeclock+The time logging format of timeclock.el, as read by hledger.+.PP+hledger can read time logs in timeclock format.+As with Ledger, these are (a subset of) timeclock.el\[aq]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 \f[CR]#\f[R] or \f[CR];\f[R] or \f[CR]*\f[R], and+blank lines, are ignored.+.IP+.EX+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+.EE+.PP+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, \f[CR]hledger print\f[R] generates these journal+entries:+.IP+.EX+$ 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+.EE+.PP+Here is a sample.timeclock to download and some queries to try:+.IP+.EX+$ 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+.EE+.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+.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]+.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.+These rely on a \[dq]timeclock\[dq] executable which I think is just the+ledger 2 executable renamed.+.PP+.SH Timedot+\f[CR]timedot\f[R] format is hledger\[aq]s human\-friendly time logging+format.+Compared to \f[CR]timeclock\f[R] 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:+.IP+.EX+2023\-05\-01+hom:errands          .... ....  ; two hours; the space is ignored+fos:hledger:timedot  ..         ; half an hour+per:admin:finance               ; no time spent yet+.EE+.PP+hledger reads this as a transaction on this day with three (unbalanced)+postings, where each dot represents \[dq]0.25\[dq].+No commodity symbol is assumed, but we typically interpret it as hours.+.IP+.EX+$ 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+.EE+.PP+A timedot file contains a series of transactions (usually one per day).+Each begins with a \f[B]simple date\f[R] (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.+.PP+After the date line are zero or more time postings, consisting of:+.IP \[bu] 2+\f[B]An account name\f[R] \- any hledger\-style account name, optionally+indented.+.IP \[bu] 2+\f[B]Two or more spaces\f[R] \- required if there is an amount (as in+journal format).+.IP \[bu] 2+\f[B]A timedot amount\f[R], which can be+.RS 2+.IP \[bu] 2+empty (representing zero)+.IP \[bu] 2+a number, optionally followed by a unit \f[CR]s\f[R], \f[CR]m\f[R],+\f[CR]h\f[R], \f[CR]d\f[R], \f[CR]w\f[R], \f[CR]mo\f[R], or+\f[CR]y\f[R], 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.+.IP \[bu] 2+one or more dots (period characters), each representing 0.25.+These are the dots in \[dq]timedot\[dq].+Spaces are ignored and can be used for grouping/alignment.+.IP \[bu] 2+\f[I]Added in 1.32\f[R] one or more letters.+These are like dots but they also generate a tag \f[CR]t:\f[R] (short+for \[dq]type\[dq]) 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 \f[CR]\-\-pivot t\f[R].+.RE+.IP \[bu] 2+\f[B]An optional comment\f[R] following a semicolon (a hledger\-style+posting comment).+.PP+There is some flexibility to help with keeping time log data and notes+in the same file:+.IP \[bu] 2+Blank lines and lines beginning with \f[CR]#\f[R] or \f[CR];\f[R] are+ignored.+.IP \[bu] 2+After the first date line, lines which do not contain a double space are+parsed as postings with zero amount.+(hledger\[aq]s register reports will show these if you add \-E).+.IP \[bu] 2+Before the first date line, lines beginning with \f[CR]*\f[R] (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 \f[CR]*\f[R]\[aq]s followed by a space)+will be ignored.+This means the time log can also be a org outline.+.SS Timedot examples+Numbers:+.IP+.EX+2016/2/3+inc:client1   4+fos:hledger   3h+biz:research  60m+.EE+.PP+Dots:+.IP+.EX+# 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  .+.EE+.IP+.EX+$ hledger \-f a.timedot print date:2016/2/2+2016\-02\-02 *+    (inc:client1)          2.00++2016\-02\-02 *+    (biz:research)          0.25+.EE+.IP+.EX+$ 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 +.EE+.PP+Letters:+.IP+.EX+# Activity types:+#  c cleanup/catchup/repair+#  e enhancement+#  s support+#  l learning/research++2023\-11\-01+work:adm  ccecces+.EE+.IP+.EX+$ 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+.EE+.IP+.EX+$ hledger \-f a.timedot bal+                1.75  work:adm+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+                1.75  +.EE+.IP+.EX+$ hledger \-f a.timedot bal \-\-pivot t+                1.00  c+                0.50  e+                0.25  s+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+                1.75  +.EE+.PP+Org:+.IP+.EX+* 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+.EE+.PP+Using \f[CR].\f[R] as account name separator:+.IP+.EX+2016/2/4+fos.hledger.timedot  4h+fos.ledger           ..+.EE+.IP+.EX+$ hledger \-f a.timedot \-\-alias \[aq]/\[rs]./=:\[aq] bal \-t+                4.50  fos+                4.00    hledger:timedot+                0.50    ledger+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+                4.50+.EE+.SH PART 3: REPORTING CONCEPTS+.SH Time periods+.SS 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.+.PP+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+\f[CR]\-b/\-\-begin\f[R], \f[CR]\-e/\-\-end\f[R], or+\f[CR]\-p/\-\-period\f[R] options, or a \f[CR]date:\f[R] query argument,+described below.+All of these accept the smart date syntax, also described below.+.PP+End dates are exclusive; specify the day after the last day you want to+see in the report.+.PP+When dates are specified by multiple options, the last (right\-most)+option wins.+And when \f[CR]date:\f[R] queries and date options are combined, the+report period will be their intersection.+.PP+Examples:+.TP+\f[CR]\-b 2016/3/17\f[R]+beginning on St.+Patrick\[cq]s day 2016+.TP+\f[CR]\-e 12/1\f[R]+ending at the start of December 1st in the current year+.TP+\f[CR]\-p \[aq]this month\[aq]\f[R]+during the current month+.TP+\f[CR]\-p thismonth\f[R]+same as above, spaces are optional+.TP+\f[CR]\-b 2023\f[R]+beginning on the first day of 2023+.TP+\f[CR]date:2023..\f[R] or \f[CR]date:2023\-\f[R]+same as above+.PP+\f[CR]\-b 2024 \-e 2025 \-p \[aq]2000 to 2030\[aq] date:2020\-01 date:2020\f[R]+:+.PD 0+.P+.PD+during January 2020 (the smallest common period, with the \-p overriding+\-b and \-e)+.SS Smart dates+In hledger\[aq]s user interfaces (though not in the journal file), you+can optionally use \[dq]smart date\[dq] 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.+.PP+Examples:+.PP+\f[CR]2004\-01\-01\f[R], \f[CR]2004/10/1\f[R], \f[CR]2004.9.1\f[R],+\f[CR]20240504\f[R] :+.PD 0+.P+.PD+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 \f[CR]\-\f[R] or \f[CR]/\f[R] or+\f[CR].\f[R] or nothing.+.TP+\f[CR]2004\-10\f[R]+start of month+.TP+\f[CR]2004\f[R]+start of year+.TP+\f[CR]10/1\f[R] or \f[CR]oct\f[R] or \f[CR]october\f[R]+October 1st in current year+.TP+\f[CR]21\f[R]+21st day in current month+.TP+\f[CR]yesterday, today, tomorrow\f[R]+\-1, 0, 1 days from today+.TP+\f[CR]last/this/next day/week/month/quarter/year\f[R]+\-1, 0, 1 periods from the current period+.TP+\f[CR]in n days/weeks/months/quarters/years\f[R]+n periods from the current period+.TP+\f[CR]n days/weeks/months/quarters/years ahead\f[R]+n periods from the current period+.TP+\f[CR]n days/weeks/months/quarters/years ago\f[R]+\-n periods from the current period+.TP+\f[CR]20181201\f[R]+8 digit YYYYMMDD with valid year month and day+.TP+\f[CR]201812\f[R]+6 digit YYYYMM with valid year and month+.PP+Dates with no separators are allowed but might give surprising results+if mistyped:+.IP \[bu] 2+\f[CR]20181301\f[R] (YYYYMMDD with an invalid month) is parsed as an+eight\-digit year+.IP \[bu] 2+\f[CR]20181232\f[R] (YYYYMMDD with an invalid day) gives a parse error+.IP \[bu] 2+\f[CR]201801012\f[R] (a valid YYYYMMDD followed by additional digits)+gives a parse error+.PP+The meaning of relative dates depends on today\[aq]s date.+If you need to test or reproduce old reports, you can use the+\f[CR]\-\-today\f[R] option to override that.+(Except for periodic transaction rules, which are not affected by+\f[CR]\-\-today\f[R].)+.SS 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.+.PP+The following standard intervals can be enabled with command\-line+flags:+.IP \[bu] 2+\f[CR]\-D/\-\-daily\f[R]+.IP \[bu] 2+\f[CR]\-W/\-\-weekly\f[R]+.IP \[bu] 2+\f[CR]\-M/\-\-monthly\f[R]+.IP \[bu] 2+\f[CR]\-Q/\-\-quarterly\f[R]+.IP \[bu] 2+\f[CR]\-Y/\-\-yearly\f[R]+.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:+.IP \[bu] 2+an inferred start date will be adjusted earlier if needed to fall on a+natural period boundary+.IP \[bu] 2+an inferred end date will be adjusted later if needed to make the last+period the same length as the others.+.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.+.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+report interval.+.PP+Here\[aq]s a period expression with a start and end date (specifying the+first quarter of 2009):+.PP+.TS+tab(@);+l.+T{+\f[CR]\-p \[dq]from 2009/1/1 to 2009/4/1\[dq]\f[R]+T}+.TE+.PP+Several keywords like \[dq]from\[dq] and \[dq]to\[dq] are supported for+readability; these are optional.+\[dq]to\[dq] can also be written as \[dq]..\[dq] or \[dq]\-\[dq].+The spaces are also optional, as long as you don\[aq]t run two dates+together.+So the following are equivalent to the above:+.PP+.TS+tab(@);+l.+T{+\f[CR]\-p \[dq]2009/1/1 2009/4/1\[dq]\f[R]+T}+T{+\f[CR]\-p2009/1/1to2009/4/1\f[R]+T}+T{+\f[CR]\-p2009/1/1..2009/4/1\f[R]+T}+.TE+.PP+Dates are smart dates, so if the current year is 2009, these are also+equivalent to the above:+.PP+.TS+tab(@);+l.+T{+\f[CR]\-p \[dq]1/1 4/1\[dq]\f[R]+T}+T{+\f[CR]\-p \[dq]jan\-apr\[dq]\f[R]+T}+T{+\f[CR]\-p \[dq]this year to 4/1\[dq]\f[R]+T}+.TE+.PP+If you specify only one date, the missing start or end date will be the+earliest or latest transaction date in the journal:+.PP+.TS+tab(@);+l l.+T{+\f[CR]\-p \[dq]from 2009/1/1\[dq]\f[R]+T}@T{+everything after january 1, 2009+T}+T{+\f[CR]\-p \[dq]since 2009/1\[dq]\f[R]+T}@T{+the same, since is a synonym+T}+T{+\f[CR]\-p \[dq]from 2009\[dq]\f[R]+T}@T{+the same+T}+T{+\f[CR]\-p \[dq]to 2009\[dq]\f[R]+T}@T{+everything before january 1, 2009+T}+.TE+.PP+You can also specify a period by writing a single partial or full date:+.PP+.TS+tab(@);+lw(14.5n) lw(55.5n).+T{+\f[CR]\-p \[dq]2009\[dq]\f[R]+T}@T{+the year 2009; equivalent to \[lq]2009/1/1 to 2010/1/1\[rq]+T}+T{+\f[CR]\-p \[dq]2009/1\[dq]\f[R]+T}@T{+the month of january 2009; equivalent to \[lq]2009/1/1 to 2009/2/1\[rq]+T}+T{+\f[CR]\-p \[dq]2009/1/1\[dq]\f[R]+T}@T{+the first day of 2009; equivalent to \[lq]2009/1/1 to 2009/1/2\[rq]+T}+.TE+.PP+or by using the \[dq]Q\[dq] quarter\-year syntax (case insensitive):+.PP+.TS+tab(@);+lw(15.3n) lw(54.7n).+T{+\f[CR]\-p \[dq]2009Q1\[dq]\f[R]+T}@T{+first quarter of 2009, equivalent to \[lq]2009/1/1 to 2009/4/1\[rq]+T}+T{+\f[CR]\-p \[dq]q4\[dq]\f[R]+T}@T{+fourth quarter of the current year+T}+.TE+.SS 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 \f[CR]in\f[R]:+.PP+.TS+tab(@);+l.+T{+\f[CR]\-p \[dq]weekly from 2009/1/1 to 2009/4/1\[dq]\f[R]+T}+T{+\f[CR]\-p \[dq]monthly in 2008\[dq]\f[R]+T}+T{+\f[CR]\-p \[dq]quarterly\[dq]\f[R]+T}+.TE+.SS More complex report intervals+Some more complex intervals can be specified within period expressions,+such as:+.IP \[bu] 2+\f[CR]biweekly\f[R] (every two weeks)+.IP \[bu] 2+\f[CR]fortnightly\f[R]+.IP \[bu] 2+\f[CR]bimonthly\f[R] (every two months)+.IP \[bu] 2+\f[CR]every day|week|month|quarter|year\f[R]+.IP \[bu] 2+\f[CR]every N days|weeks|months|quarters|years\f[R]+.PP+Weekly on a custom day:+.IP \[bu] 2+\f[CR]every Nth day of week\f[R] (\f[CR]th\f[R], \f[CR]nd\f[R],+\f[CR]rd\f[R], or \f[CR]st\f[R] are all accepted after the number)+.IP \[bu] 2+\f[CR]every WEEKDAYNAME\f[R] (full or three\-letter english weekday+name, case insensitive)+.PP+Monthly on a custom day:+.IP \[bu] 2+\f[CR]every Nth day [of month]\f[R] (\f[CR]31st day\f[R] will be+adjusted to each month\[aq]s last day)+.IP \[bu] 2+\f[CR]every Nth WEEKDAYNAME [of month]\f[R]+.PP+Yearly on a custom day:+.IP \[bu] 2+\f[CR]every MM/DD [of year]\f[R] (month number and day of month number)+.IP \[bu] 2+\f[CR]every MONTHNAME DDth [of year]\f[R] (full or three\-letter english+month name, case insensitive, and day of month number)+.IP \[bu] 2+\f[CR]every DDth MONTHNAME [of year]\f[R] (equivalent to the above)+.PP+Examples:+.PP+.TS+tab(@);+lw(26.8n) lw(43.2n).+T{+\f[CR]\-p \[dq]bimonthly from 2008\[dq]\f[R]+T}@T{+T}+T{+\f[CR]\-p \[dq]every 2 weeks\[dq]\f[R]+T}@T{+T}+T{+\f[CR]\-p \[dq]every 5 months from 2009/03\[dq]\f[R]+T}@T{+T}+T{+\f[CR]\-p \[dq]every 2nd day of week\[dq]\f[R]+T}@T{+periods will go from Tue to Tue+T}+T{+\f[CR]\-p \[dq]every Tue\[dq]\f[R]+T}@T{+same+T}+T{+\f[CR]\-p \[dq]every 15th day\[dq]\f[R]+T}@T{+period boundaries will be on 15th of each month+T}+T{+\f[CR]\-p \[dq]every 2nd Monday\[dq]\f[R]+T}@T{+period boundaries will be on second Monday of each month+T}+T{+\f[CR]\-p \[dq]every 11/05\[dq]\f[R]+T}@T{+yearly periods with boundaries on 5th of November+T}+T{+\f[CR]\-p \[dq]every 5th November\[dq]\f[R]+T}@T{+same+T}+T{+\f[CR]\-p \[dq]every Nov 5th\[dq]\f[R]+T}@T{+same+T}+.TE+.PP+Show historical balances at end of the 15th day of each month (N is an+end date, exclusive as always):+.IP+.EX+$ hledger balance \-H \-p \[dq]every 16th day\[dq]+.EE+.PP+Group postings from the start of wednesday to end of the following+tuesday (N is both (inclusive) start date and (exclusive) end date):+.IP+.EX+$ hledger register checking \-p \[dq]every 3rd day of week\[dq]+.EE+.SS Multiple weekday intervals+This special form is also supported:+.IP \[bu] 2+\f[CR]every WEEKDAYNAME,WEEKDAYNAME,...\f[R] (full or three\-letter+english weekday names, case insensitive)+.PP+Also, \f[CR]weekday\f[R] and \f[CR]weekendday\f[R] are shorthand for+\f[CR]mon,tue,wed,thu,fri\f[R] and \f[CR]sat,sun\f[R].+.PP+This is mainly intended for use with \f[CR]\-\-forecast\f[R], to+generate periodic transactions on arbitrary days of the week.+It may be less useful with \f[CR]\-p\f[R], since it divides each week+into subperiods of unequal length, which is unusual.+(Related: #1632)+.PP+Examples:+.PP+.TS+tab(@);+lw(17.8n) lw(52.2n).+T{+\f[CR]\-p \[dq]every mon,wed,fri\[dq]\f[R]+T}@T{+dates will be Mon, Wed, Fri; periods will be Mon\-Tue, Wed\-Thu,+Fri\-Sun+T}+T{+\f[CR]\-p \[dq]every weekday\[dq]\f[R]+T}@T{+dates will be Mon, Tue, Wed, Thu, Fri; periods will be Mon, Tue, Wed,+Thu, Fri\-Sun+T}+T{+\f[CR]\-p \[dq]every weekendday\[dq]\f[R]+T}@T{+dates will be Sat, Sun; periods will be Sat, Sun\-Fri+T}+.TE+.SH Depth+With the \f[CR]\-\-depth NUM\f[R] option (short form: \f[CR]\-NUM\f[R]),+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 \f[CR]depth:\f[R] query argument:+\f[CR]depth:2\f[R], \f[CR]\-\-depth=2\f[R] or \f[CR]\-2\f[R] are+equivalent.+.SH Queries+One of hledger\[aq]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.+.IP \[bu] 2+By default, a query term is interpreted as a case\-insensitive substring+pattern for matching account names:+.RS 2+.PP+\f[CR]car:fuel\f[R]+.PD 0+.P+.PD+\f[CR]dining groceries\f[R]+.PD 0+.P+.PD+.RE+.IP \[bu] 2+Patterns containing spaces or other special characters must be enclosed+in single or double quotes:+.RS 2+.PP+\f[CR]\[aq]personal care\[aq]\f[R]+.PD 0+.P+.PD+.RE+.IP \[bu] 2+These patterns are actually regular expressions, so you can add regexp+metacharacters for more precision (see \[dq]Regular expressions\[dq]+above for details):+.RS 2+.PP+\f[CR]\[aq]\[ha]expenses\[rs]b\[aq]\f[R]+.PD 0+.P+.PD+\f[CR]\[aq]food$\[aq]\f[R]+.PD 0+.P+.PD+\f[CR]\[aq]fuel|repair\[aq]\f[R]+.PD 0+.P+.PD+\f[CR]\[aq]accounts (payable|receivable)\[aq]\f[R]+.PD 0+.P+.PD+.RE+.IP \[bu] 2+To match something other than account name, add one of the query type+prefixes described in \[dq]Query types\[dq] below:+.RS 2+.PP+\f[CR]date:202312\-\f[R]+.PD 0+.P+.PD+\f[CR]status:\f[R]+.PD 0+.P+.PD+\f[CR]desc:amazon\f[R]+.PD 0+.P+.PD+\f[CR]cur:USD\f[R]+.PD 0+.P+.PD+\f[CR]cur:\[rs]\[rs]$\f[R]+.PD 0+.P+.PD+\f[CR]amt:\[aq]>0\[aq]\f[R]+.PD 0+.P+.PD+.RE+.IP \[bu] 2+Add a \f[CR]not:\f[R] prefix to negate a term:+.RS 2+.PP+\f[CR]not:status:\[aq]*\[aq]\f[R]+.PD 0+.P+.PD+\f[CR]not:desc:\[aq]opening|closing\[aq]\f[R]+.PD 0+.P+.PD+\f[CR]not:cur:USD\f[R]+.PD 0+.P+.PD+.RE+.IP \[bu] 2+Terms with different types are AND\-ed, terms with the same type are+OR\-ed (mostly; see \[dq]Combining query terms\[dq] below).+The following query:+.RS 2+.PP+\f[CR]date:2022 desc:amazon desc:amzn\f[R]+.PP+is interpreted as:+.PP+\f[I]date is in 2022 AND ( transaction description contains+\[dq]amazon\[dq] OR \[dq]amzn\[dq] )\f[R]+.RE+.SS Query types+Here are the types of query term available.+Remember these can also be prefixed with \f[B]\f[CB]not:\f[B]\f[R] to+convert them into a negative match.+.PP+\f[B]\f[CB]acct:REGEX\f[B]\f[R] or \f[B]\f[CB]REGEX\f[B]\f[R]+.PD 0+.P+.PD+Match account names containing this case insensitive regular expression.+This is the default query type, so we usually don\[aq]t bother writing+the \[dq]acct:\[dq] prefix.+.PP+\f[B]\f[CB]amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N\f[B]\f[R]+.PD 0+.P+.PD+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.+.PP+\f[B]\f[CB]code:REGEX\f[B]\f[R]+.PD 0+.P+.PD+Match by transaction code (eg check number).+.PP+\f[B]\f[CB]cur:REGEX\f[B]\f[R]+.PD 0+.P+.PD+Match postings or transactions including any amounts whose+currency/commodity symbol is fully matched by REGEX.+(For a partial match, use \f[CR].*REGEX.*\f[R]).+Note, to match special characters which are regex\-significant, you need+to escape them with \f[CR]\[rs]\f[R].+And for characters which are significant to your shell you may need one+more level of escaping.+So eg to match the dollar sign:+.PD 0+.P+.PD+\f[CR]hledger print cur:\[rs]\[rs]$\f[R].+.PP+\f[B]\f[CB]desc:REGEX\f[B]\f[R]+.PD 0+.P+.PD+Match transaction descriptions.+.PP+\f[B]\f[CB]date:PERIODEXPR\f[B]\f[R]+.PD 0+.P+.PD+Match dates (or with the \f[CR]\-\-date2\f[R] flag, secondary dates)+within the specified period.+PERIODEXPR is a period expression with no report interval.+Examples:+.PD 0+.P+.PD+\f[CR]date:2016\f[R], \f[CR]date:thismonth\f[R],+\f[CR]date:2/1\-2/15\f[R], \f[CR]date:2021\-07\-27..nextquarter\f[R].+.PP+\f[B]\f[CB]date2:PERIODEXPR\f[B]\f[R]+.PD 0+.P+.PD+Match secondary dates within the specified period (independent of the+\f[CR]\-\-date2\f[R] flag).+.PP+\f[B]\f[CB]depth:N\f[B]\f[R]+.PD 0+.P+.PD+Match (or display, depending on command) accounts at or above this+depth.+.PP+\f[B]\f[CB]expr:\[dq]TERM AND NOT (TERM OR TERM)\[dq]\f[B]\f[R] (eg)+.PD 0+.P+.PD+Match with a boolean combination of queries (which must be enclosed in+quotes).+See Combining query terms below.+.PP+\f[B]\f[CB]note:REGEX\f[B]\f[R]+.PD 0+.P+.PD+Match transaction notes (the part of the description right of+\f[CR]|\f[R], or the whole description if there\[aq]s no \f[CR]|\f[R]).+.PP+\f[B]\f[CB]payee:REGEX\f[B]\f[R]+.PD 0+.P+.PD+Match transaction payee/payer names (the part of the description left of+\f[CR]|\f[R], or the whole description if there\[aq]s no \f[CR]|\f[R]).+.PP+\f[B]\f[CB]real:, real:0\f[B]\f[R]+.PD 0+.P+.PD+Match real or virtual postings respectively.+.PP+\f[B]\f[CB]status:, status:!, status:*\f[B]\f[R]+.PD 0+.P+.PD+Match unmarked, pending, or cleared transactions respectively.+.PP+\f[B]\f[CB]type:TYPECODES\f[B]\f[R]+.PD 0+.P+.PD+Match by account type (see Declaring accounts > Account types).+\f[CR]TYPECODES\f[R] is one or more of the single\-letter account type+codes \f[CR]ALERXCV\f[R], case insensitive.+Note \f[CR]type:A\f[R] and \f[CR]type:E\f[R] will also match their+respective subtypes \f[CR]C\f[R] (Cash) and \f[CR]V\f[R] (Conversion).+Certain kinds of account alias can disrupt account types, see Rewriting+accounts > Aliases and account types.+.PP+\f[B]\f[CB]tag:REGEX[=REGEX]\f[B]\f[R]+.PD 0+.P+.PD+Match by tag name, and optionally also by tag value.+(To match only by value, use \f[CR]tag:.=REGEX\f[R].)+.PP+When querying by tag, note that:+.IP \[bu] 2+Accounts also inherit the tags of their parent accounts+.IP \[bu] 2+Postings also inherit the tags of their account and their transaction+.IP \[bu] 2+Transactions also acquire the tags of their postings.+.PP+(\f[B]\f[CB]inacct:ACCTNAME\f[B]\f[R]+.PD 0+.P+.PD+A special query term used automatically in hledger\-web only: tells+hledger\-web to show the transaction register for an account.)+.SS Combining query terms+When given multiple space\-separated query terms, most commands select+things which match:+.IP \[bu] 2+any of the description terms AND+.IP \[bu] 2+any of the account terms AND+.IP \[bu] 2+any of the status terms AND+.IP \[bu] 2+all the other terms.+.PP+The print command is a little different, showing transactions which:+.IP \[bu] 2+match any of the description terms AND+.IP \[bu] 2+have any postings matching any of the positive account terms AND+.IP \[bu] 2+have no postings matching any of the negative account terms AND+.IP \[bu] 2+match all the other terms.+.PP+We also support more complex boolean queries with the \f[CR]expr:\f[R]+prefix.+This allows one to combine query terms using \f[CR]and\f[R],+\f[CR]or\f[R], \f[CR]not\f[R] keywords (case insensitive), and to group+them by enclosing in parentheses.+.PP+Some examples:+.IP \[bu] 2+Exclude account names containing \[aq]food\[aq]:+.RS 2+.PP+\f[CR]expr:\[dq]not food\[dq]\f[R] (\f[CR]not:food\f[R] is equivalent)+.RE+.IP \[bu] 2+Match things which have \[aq]cool\[aq] in the description and the+\[aq]A\[aq] tag:+.RS 2+.PP+\f[CR]expr:\[dq]desc:cool and tag:A\[dq]\f[R]+(\f[CR]expr:\[dq]desc:cool tag:A\[dq]\f[R] is equivalent)+.RE+.IP \[bu] 2+Match things which either do not reference the \[aq]expenses:food\[aq]+account, or do have the \[aq]A\[aq] tag:+.RS 2+.PP+\f[CR]expr:\[dq]not expenses:food or tag:A\[dq]\f[R]+.RE+.IP \[bu] 2+Match things which either do not reference the \[aq]expenses:food\[aq]+account, or which reference the \[aq]expenses:drink\[aq] account and+also have the \[aq]A\[aq] tag:+.RS 2+.PP+\f[CR]expr:\[dq]expenses:food or (expenses:drink and tag:A)\[dq]\f[R]+.RE+.PP+\f[CR]expr:\f[R] has a restriction: \f[CR]date:\f[R] queries may not be+used inside \f[CR]or\f[R] expressions.+That would allow disjoint report periods or disjoint result sets, with+unclear semantics for our reports.+.SS Queries and command options+Some queries can also be expressed as command\-line options:+\f[CR]depth:2\f[R] is equivalent to \f[CR]\-\-depth 2\f[R],+\f[CR]date:2023\f[R] is equivalent to \f[CR]\-p 2023\f[R], etc.+When you mix command options and query arguments, generally the+resulting query is their intersection.+.SS Queries and account aliases+When account names are rewritten with \f[CR]\-\-alias\f[R] or+\f[CR]alias\f[R], \f[CR]acct:\f[R] will match either the old or the new+account name.+.SS Queries and valuation+When amounts are converted to other commodities in cost or value+reports, \f[CR]cur:\f[R] and \f[CR]amt:\f[R] match the old commodity+symbol and the old amount quantity, not the new ones.+(Except in hledger 1.22, #1625.)+.SH Pivoting+Normally, hledger groups and sums amounts within each account.+The \f[CR]\-\-pivot FIELD\f[R] option substitutes some other transaction+field for account names, causing amounts to be grouped and summed by+that field\[aq]s value instead.+FIELD can be any of the transaction fields \f[CR]acct\f[R],+\f[CR]status\f[R], \f[CR]code\f[R], \f[CR]desc\f[R], \f[CR]payee\f[R],+\f[CR]note\f[R], or a tag name.+When pivoting on a tag and a posting has multiple values of that tag,+only the first value is displayed.+Values containing \f[CR]colon:separated:parts\f[R] will be displayed+hierarchically, like account names.+Multiple, colon\-delimited fields can be pivoted simultaneously,+generating a hierarchical account name.+.PP+Some examples:+.IP+.EX+2016/02/16 Yearly Dues Payment+    assets:bank account                 2 EUR+    income:dues                        \-2 EUR  ; member: John Doe, kind: Lifetime+.EE+.PP+Normal balance report showing account names:+.IP+.EX+$ hledger balance+               2 EUR  assets:bank account+              \-2 EUR  income:dues+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+                   0+.EE+.PP+Pivoted balance report, using member: tag values instead:+.IP+.EX+$ hledger balance \-\-pivot member+               2 EUR+              \-2 EUR  John Doe+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+                   0+.EE+.PP+One way to show only amounts with a member: value (using a query):+.IP+.EX+$ hledger balance \-\-pivot member tag:member=.+              \-2 EUR  John Doe+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+              \-2 EUR+.EE+.PP+Another way (the acct: query matches against the pivoted \[dq]account+name\[dq]):+.IP+.EX+$ hledger balance \-\-pivot member acct:.+              \-2 EUR  John Doe+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+              \-2 EUR+.EE+.PP+Hierarchical reports can be generated with multiple pivots:+.IP+.EX+$ hledger balance Income:Dues \-\-pivot kind:member+              \-2 EUR  Lifetime:John Doe+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+              \-2 EUR+.EE+.SH 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:+.IP \[bu] 2+Missing amounts or missing costs in transactions are inferred+automatically when possible.+.IP \[bu] 2+The \f[CR]\-\-infer\-equity\f[R] flag infers missing conversion equity+postings from \[at]/\[at]\[at] costs.+.IP \[bu] 2+The \f[CR]\-\-infer\-costs\f[R] flag infers missing costs from+conversion equity postings.+.IP \[bu] 2+The \f[CR]\-\-infer\-market\-prices\f[R] flag infers \f[CR]P\f[R] price+directives from costs.+.IP \[bu] 2+The \f[CR]\-\-auto\f[R] flag adds extra postings to transactions matched+by auto posting rules.+.IP \[bu] 2+The \f[CR]\-\-forecast\f[R] option generates transactions from periodic+transaction rules.+.IP \[bu] 2+The \f[CR]balance \-\-budget\f[R] report infers budget goals from+periodic transaction rules.+.IP \[bu] 2+Commands like \f[CR]close\f[R], \f[CR]rewrite\f[R], and+\f[CR]hledger\-interest\f[R] generate transactions or postings.+.IP \[bu] 2+CSV data is converted to transactions by applying CSV conversion rules..+etc.+.PP+Such generated data is temporary, existing only at report time.+You can convert it to permanent recorded data by, eg, capturing the+output of \f[CR]hledger print\f[R] and saving it in your journal file.+This can sometimes be useful as a data entry aid.+.PP+If you are curious what data is being generated and why, run+\f[CR]hledger print \-x \-\-verbose\-tags\f[R].+\f[CR]\-x/\-\-explicit\f[R] shows inferred amounts and+\f[CR]\-\-verbose\-tags\f[R] adds tags like+\f[CR]generated\-transaction\f[R] (from periodic rules) and+\f[CR]generated\-posting\f[R], \f[CR]modified\f[R] (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+\f[CR]tag:generated\f[R] or \f[CR]tag:modified\f[R].+.SH Forecasting+Forecasting, or speculative future reporting, can be useful for+estimating future balances, or for exploring different future scenarios.+.PP+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 \f[CR]future.journal\f[R] and include+that with \f[CR]\-f\f[R] only when you want to see them.+.SS \-\-forecast+There is another way: with the \f[CR]\-\-forecast\f[R] option, hledger+can generate temporary \[dq]forecast transactions\[dq] 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.+.PP+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.)+.PP+This is the \[dq]forecast period\[dq], 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+\f[CR]\-\-forecast=..2099\f[R] or+\f[CR]\-\-forecast=2023\-02\-15..\f[R].+Note that the \f[CR]=\f[R] is required.+.SS Inspecting forecast transactions+\f[CR]print\f[R] is the best command for inspecting and troubleshooting+forecast transactions.+Eg:+.IP+.EX+\[ti] monthly from 2022\-12\-20    rent+    assets:bank:checking+    expenses:rent           $1000+.EE+.IP+.EX+$ hledger print \-\-forecast \-\-today=2023/4/21+2023\-05\-20 rent+    ; generated\-transaction: \[ti] monthly from 2022\-12\-20+    assets:bank:checking+    expenses:rent                  $1000++2023\-06\-20 rent+    ; generated\-transaction: \[ti] monthly from 2022\-12\-20+    assets:bank:checking+    expenses:rent                  $1000++2023\-07\-20 rent+    ; generated\-transaction: \[ti] monthly from 2022\-12\-20+    assets:bank:checking+    expenses:rent                  $1000++2023\-08\-20 rent+    ; generated\-transaction: \[ti] monthly from 2022\-12\-20+    assets:bank:checking+    expenses:rent                  $1000++2023\-09\-20 rent+    ; generated\-transaction: \[ti] monthly from 2022\-12\-20+    assets:bank:checking+    expenses:rent                  $1000+.EE+.PP+Here there are no ordinary transactions, so the forecasted transactions+begin on the first occurence 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+Forecast transactions affect all reports, as you would expect.+Eg:+.IP+.EX+$ 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+.EE+.IP+.EX+$ 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 +.EE+.SS Forecast tags+Forecast transactions generated by \-\-forecast have a hidden tag,+\f[CR]_generated\-transaction\f[R].+So if you ever need to match forecast transactions, you could use+\f[CR]tag:_generated\-transaction\f[R] (or just+\f[CR]tag:generated\f[R]) in a query.+.PP+For troubleshooting, you can add the \f[CR]\-\-verbose\-tags\f[R] flag.+Then, visible \f[CR]generated\-transaction\f[R] tags will be added also,+so you can view them with the \f[CR]print\f[R] command.+Their value indicates which periodic rule was responsible.+.SS 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:+.PP+The forecast period starts on:+.IP \[bu] 2+the later of+.RS 2+.IP \[bu] 2+the start date in the periodic transaction rule+.IP \[bu] 2+the start date in \f[CR]\-\-forecast\f[R]\[aq]s argument+.RE+.IP \[bu] 2+otherwise (if those are not available): the later of+.RS 2+.IP \[bu] 2+the report start date specified with+\f[CR]\-b\f[R]/\f[CR]\-p\f[R]/\f[CR]date:\f[R]+.IP \[bu] 2+the day after the latest ordinary transaction in the journal+.RE+.IP \[bu] 2+otherwise (if none of these are available): today.+.PP+The forecast period ends on:+.IP \[bu] 2+the earlier of+.RS 2+.IP \[bu] 2+the end date in the periodic transaction rule+.IP \[bu] 2+the end date in \f[CR]\-\-forecast\f[R]\[aq]s argument+.RE+.IP \[bu] 2+otherwise: the report end date specified with+\f[CR]\-e\f[R]/\f[CR]\-p\f[R]/\f[CR]date:\f[R]+.IP \[bu] 2+otherwise: 180 days (\[ti]6 months) from today.+.SS Forecast troubleshooting+When \-\-forecast is not doing what you expect, one of these tips should+help:+.IP \[bu] 2+Remember to use the \f[CR]\-\-forecast\f[R] option.+.IP \[bu] 2+Remember to have at least one periodic transaction rule in your journal.+.IP \[bu] 2+Test with \f[CR]print \-\-forecast\f[R].+.IP \[bu] 2+Check for typos or too\-restrictive start/end dates in your periodic+transaction rule.+.IP \[bu] 2+Leave at least 2 spaces between the rule\[aq]s period expression and+description fields.+.IP \[bu] 2+Check for future\-dated ordinary transactions suppressing forecasted+transactions.+.IP \[bu] 2+Try setting explicit report start and/or end dates with \f[CR]\-b\f[R],+\f[CR]\-e\f[R], \f[CR]\-p\f[R] or \f[CR]date:\f[R]+.IP \[bu] 2+Try adding the \f[CR]\-E\f[R] flag to encourage display of empty+periods/zero transactions.+.IP \[bu] 2+Try setting explicit forecast start and/or end dates with+\f[CR]\-\-forecast=START..END\f[R]+.IP \[bu] 2+Consult Forecast period, in detail, above.+.IP \[bu] 2+Check inside the engine: add \f[CR]\-\-debug=2\f[R] (eg).+.SH Budgeting+With the balance command\[aq]s \f[CR]\-\-budget\f[R] report, each+periodic transaction rule generates recurring budget goals in specified+accounts, and goals and actual performance can be compared.+See the balance command\[aq]s doc below.+.PP+You can generate budget goals and forecast transactions at the same+time, from the same or different periodic transaction rules:+\f[CR]hledger bal \-M \-\-budget \-\-forecast ...\f[R]+.PP+See also: Budgeting and Forecasting.+.SH Amount formatting+.SS 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:+.PP+First, if there\[aq]s a \f[CR]D\f[R] directive declaring a default+commodity, that commodity symbol and amount format is applied to all+no\-symbol amounts in the journal.+.PP+Then each commodity\[aq]s display style is determined from its+\f[CR]commodity\f[R] directive.+We recommend always declaring commodities with \f[CR]commodity\f[R]+directives, since they help ensure consistent display styles and+precisions, and bring other benefits such as error checking for+commodity symbols.+Here\[aq]s an example:+.IP+.EX+# 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+.EE+.PP+But for convenience, if a \f[CR]commodity\f[R] directive is not present,+hledger infers a commodity\[aq]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+.IP \[bu] 2+the symbol placement and decimal mark of the first amount seen+.IP \[bu] 2+the digit group marks of the first amount with digit group marks+.IP \[bu] 2+and the maximum number of decimal digits seen across all amounts.+.PP+And as fallback if no applicable amounts are found, it would use a+default style, like \f[CR]$1000.00\f[R] (symbol on the left with no+space, period as decimal mark, and two decimal digits).+.PP+Finally, commodity styles can be overridden by the+\f[CR]\-c/\-\-commodity\-style\f[R] command line option.+.SS 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\[aq]s rounding (it rounds to the+nearest even digit).+So eg 0.5 displayed with zero decimal digits appears as \[dq]0\[dq].+.SS Trailing decimal marks+If you\[aq]re wondering why your \f[CR]print\f[R] 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:+.IP+.EX+commodity $1,000.00++2023\-01\-02+    (a)      $1000+.EE+.IP+.EX+$ hledger print+2023\-01\-02+    (a)        $1,000.+.EE+.PP+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):+.IP+.EX+$ hledger print \-c \[aq]$1000.00\[aq]+2023\-01\-02+    (a)          $1000+.EE+.PP+or by forcing print to always show decimal digits, with \-\-round:+.IP+.EX+$ hledger print \-c \[aq]$1,000.00\[aq] \-\-round=soft+2023\-01\-02+    (a)      $1,000.00+.EE+.SS Amount parseability+More generally, hledger output falls into three rough categories, which+format amounts a little bit differently to suit different consumers:+.PP+\f[B]1.+\[dq]hledger\-readable output\[dq] \- should be readable by hledger (and+by humans)\f[R]+.IP \[bu] 2+This is produced by reports that show full journal entries:+\f[CR]print\f[R], \f[CR]import\f[R], \f[CR]close\f[R],+\f[CR]rewrite\f[R] etc.+.IP \[bu] 2+It shows amounts with their original journal precisions, which may not+be consistent.+.IP \[bu] 2+It adds a trailing decimal mark when needed to avoid showing ambiguous+amounts.+.IP \[bu] 2+It can be parsed reliably (by hledger and ledger2beancount at least, but+perhaps not by Ledger..)+.PP+\f[B]2.+\[dq]human\-readable output\[dq] \- usually for humans\f[R]+.IP \[bu] 2+This is produced by all other reports.+.IP \[bu] 2+It shows amounts with standard display precisions, which will be+consistent within each commodity.+.IP \[bu] 2+It shows ambiguous amounts unmodified.+.IP \[bu] 2+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).+.PP+\f[B]3.+\[dq]machine\-readable output\[dq] \- usually for other software\f[R]+.IP \[bu] 2+This is produced by all reports when an output format like+\f[CR]csv\f[R], \f[CR]tsv\f[R], \f[CR]json\f[R], or \f[CR]sql\f[R] is+selected.+.IP \[bu] 2+It shows amounts as 1 or 2 do, but without digit group marks.+.IP \[bu] 2+It can be parsed reliably (if needed, the decimal mark can be changed+with \-c/\-\-commodity\-style).+.SH 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 \[dq]cost\[dq], for convenience; feel free+to mentally translate to \[dq]conversion rate\[dq] or \[dq]selling+price\[dq] if helpful.+.SS Recording costs+We\[aq]ll explore several ways of recording transactions involving+costs.+These are also summarised at hledger Cookbook > Cost notation.+.PP+Costs can be recorded explicitly in the journal, using the+\f[CR]\[at] UNITCOST\f[R] or \f[CR]\[at]\[at] TOTALCOST\f[R] notation+described in Journal > Costs:+.PP+\f[B]Variant 1\f[R]+.IP+.EX+2022\-01\-01+  assets:dollars    $\-135+  assets:euros       €100 \[at] $1.35   ; $1.35 per euro (unit cost)+.EE+.PP+\f[B]Variant 2\f[R]+.IP+.EX+2022\-01\-01+  assets:dollars    $\-135+  assets:euros       €100 \[at]\[at] $135   ; $135 total cost+.EE+.PP+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.+.PP+Costs can also be left implicit, and hledger will infer the cost that is+consistent with a balanced transaction:+.PP+\f[B]Variant 3\f[R]+.IP+.EX+2022\-01\-01+  assets:dollars    $\-135+  assets:euros       €100+.EE+.PP+Here, hledger will attach a \f[CR]\[at]\[at] €100\f[R] cost to the first+amount (you can see it with \f[CR]hledger print \-x\f[R]).+This form looks convenient, but there are downsides:+.IP \[bu] 2+It sacrifices some error checking.+For example, if you accidentally wrote €10 instead of €100, hledger+would not be able to detect the mistake.+.IP \[bu] 2+It is sensitive to the order of postings \- if they were reversed, a+different entry would be inferred and reports would be different.+.IP \[bu] 2+The per\-unit cost basis is not easy to read.+.PP+So generally this kind of entry is not recommended.+You can make sure you have none of these by using \f[CR]\-s\f[R] (strict+mode), or by running \f[CR]hledger check balanced\f[R].+.SS Reporting at cost+Now when you add the \f[CR]\-B\f[R]/\f[CR]\-\-cost\f[R] flag to reports+(\[dq]B\[dq] is from Ledger\[aq]s \-B/\-\-basis/\-\-cost flag), any+amounts which have been annotated with costs will be converted to their+cost\[aq]s commodity (in the report output).+Ie they will be displayed \[dq]at cost\[dq] or \[dq]at sale price\[dq].+.PP+Some things to note:+.IP \[bu] 2+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.+.IP \[bu] 2+Conversion to cost is performed before conversion to market value+(described below).+.SS Equity conversion postings+There is a problem with the entries above \- they are not conventional+Double Entry Bookkeeping (DEB) notation, and because of the+\[dq]magical\[dq] 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+\f[CR]hledger bse\f[R].+.PP+For most hledger users, this doesn\[aq]t matter in practice and can+safely be ignored !+But if you\[aq]d like to learn more, keep reading.+.PP+Conventional DEB uses an extra pair of equity postings to balance the+transaction.+Of course you can do this in hledger as well:+.PP+\f[B]Variant 4\f[R]+.IP+.EX+2022\-01\-01+    assets:dollars      $\-135+    assets:euros         €100+    equity:conversion    $135+    equity:conversion   €\-100+.EE+.PP+Now the transaction is perfectly balanced according to standard DEB, and+\f[CR]hledger bse\f[R]\[aq]s total will not be disrupted.+.PP+And, hledger can still infer the cost for cost reporting, but it\[aq]s+not done by default \- you must add the \f[CR]\-\-infer\-costs\f[R] flag+like so:+.IP+.EX+$ hledger print \-\-infer\-costs+2022\-01\-01 one hundred euros purchased at $1.35 each+    assets:dollars       $\-135 \[at]\[at] €100+    assets:euros                  €100+    equity:conversion             $135+    equity:conversion            €\-100+.EE+.IP+.EX+$ hledger bal \-\-infer\-costs \-B+               €\-100  assets:dollars                                                                                                                                              +                €100  assets:euros                                                                                                                                                +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-                                                                                                                                                              +                   0                                                                                                                                                              +.EE+.PP+Here are some downsides of this kind of entry:+.IP \[bu] 2+The per\-unit cost basis is not easy to read.+.IP \[bu] 2+Instead of \f[CR]\-B\f[R] you must remember to type+\f[CR]\-B \-\-infer\-costs\f[R].+.IP \[bu] 2+\f[CR]\-\-infer\-costs\f[R] 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.+.SS Inferring equity conversion postings+Can we go in the other direction ?+Yes, if you have transactions written with the \[at]/\[at]\[at] cost+notation, hledger can infer the missing equity postings, if you add the+\f[CR]\-\-infer\-equity\f[R] flag.+Eg:+.IP+.EX+2022\-01\-01+  assets:dollars  \-$135+  assets:euros     €100 \[at] $1.35+.EE+.IP+.EX+$ hledger print \-\-infer\-equity+2022\-01\-01+    assets:dollars                    $\-135+    assets:euros               €100 \[at] $1.35+    equity:conversion:$\-€:€           €\-100+    equity:conversion:$\-€:$         $135.00+.EE+.PP+The equity account names will be \[dq]equity:conversion:A\-B:A\[dq] and+\[dq]equity:conversion:A\-B:B\[dq] where A is the alphabetically first+commodity symbol.+You can customise the \[dq]equity:conversion\[dq] part by declaring an+account with the \f[CR]V\f[R]/\f[CR]Conversion\f[R] account type.+.SS Combining costs and equity conversion postings+Finally, you can use both the \[at]/\[at]\[at] 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:+.PP+\f[B]Variant 5\f[R]+.IP+.EX+2022\-01\-01 one hundred euros purchased at $1.35 each+    assets:dollars      $\-135+    equity:conversion    $135+    equity:conversion   €\-100+    assets:euros         €100 \[at] $1.35+.EE+.PP+All the other variants above can (usually) be rewritten to this final+form with:+.IP+.EX+$ hledger print \-x \-\-infer\-costs \-\-infer\-equity+.EE+.PP+Downsides:+.IP \[bu] 2+The precise format of the journal entry becomes more important.+If hledger can\[aq]t detect and match up the cost and equity postings,+it will give a transaction balancing error.+.IP \[bu] 2+The add command does not yet accept this kind of entry (#2056).+.IP \[bu] 2+This is the most verbose form.+.SS Requirements for detecting equity conversion postings+\f[CR]\-\-infer\-costs\f[R] has certain requirements (unlike+\f[CR]\-\-infer\-equity\f[R], which always works).+It will infer costs only in transactions with:+.IP \[bu] 2+Two non\-equity postings, in different commodities.+Their order is significant: the cost will be added to the first of them.+.IP \[bu] 2+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\[aq]s amount.+Equity conversion accounts are:+.RS 2+.IP \[bu] 2+any accounts declared with account type+\f[CR]V\f[R]/\f[CR]Conversion\f[R], or their subaccounts+.IP \[bu] 2+otherwise, accounts named \f[CR]equity:conversion\f[R],+\f[CR]equity:trade\f[R], or \f[CR]equity:trading\f[R], or their+subaccounts.+.RE+.PP+And multiple such four\-posting groups can coexist within a single+transaction.+When \f[CR]\-\-infer\-costs\f[R] fails, it does not infer a cost in that+transaction, and does not raise an error (ie, it infers costs where it+can).+.PP+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 \[dq]unbalanced+transaction\[dq] error.+.SS Infer cost and equity by default ?+Should \f[CR]\-\-infer\-costs\f[R] and \f[CR]\-\-infer\-equity\f[R] be+enabled by default ?+Try using them always, eg with a shell alias:+.IP+.EX+alias h=\[dq]hledger \-\-infer\-equity \-\-infer\-costs\[dq]+.EE+.PP+and let us know what problems you find.+.PP+.SH Value reporting+Instead of reporting amounts in their original commodity, hledger can+convert them to cost/sale amount (using the conversion rate recorded in+the transaction), and/or to market value (using some market price on a+certain date).+This is controlled by the \f[CR]\-\-value=TYPE[,COMMODITY]\f[R] option,+which will be described below.+We also provide the simpler \f[CR]\-V\f[R] and \f[CR]\-X COMMODITY\f[R]+options, and often one of these is all you need:+.SS \-V: Value+The \f[CR]\-V/\-\-market\f[R] flag converts amounts to market value in+their default \f[I]valuation commodity\f[R], using the market prices in+effect on the \f[I]valuation date(s)\f[R], if any.+More on these in a minute.+.SS \-X: Value in specified commodity+The \f[CR]\-X/\-\-exchange=COMM\f[R] option is like \f[CR]\-V\f[R],+except you tell it which currency you want to convert to, and it tries+to convert everything to that.+.SS 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 \[dq]end\[dq] dates for valuation.+More specifically:+.IP \[bu] 2+For single period reports (including normal print and register reports):+.RS 2+.IP \[bu] 2+If an explicit report end date is specified, that is used+.IP \[bu] 2+Otherwise the latest transaction date or P directive date is used (even+if it\[aq]s in the future)+.RE+.IP \[bu] 2+For multiperiod reports, each period is valued on its last day.+.PP+This can be customised with the \-\-value option described below, which+can select either \[dq]then\[dq], \[dq]end\[dq], \[dq]now\[dq], or+\[dq]custom\[dq] dates.+(Note, this has a bug in hledger\-ui <=1.31: turning on valuation with+the \f[CR]V\f[R] key always resets it to \[dq]end\[dq].)+.SS 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:+.IP "1." 3+A \f[I]declared market price\f[R] or \f[I]inferred market price\f[R]:+A\[aq]s latest market price in B on or before the valuation date as+declared by a P directive, or (with the+\f[CR]\-\-infer\-market\-prices\f[R] flag) inferred from costs.+\+.IP "2." 3+A \f[I]reverse market price\f[R]: the inverse of a declared or inferred+market price from B to A.+.IP "3." 3+A \f[I]forward chain of market prices\f[R]: a synthetic price formed by+combining the shortest chain of \[dq]forward\[dq] (only 1 above) market+prices, leading from A to B.+.IP "4." 3+\f[I]Any chain of market prices\f[R]: a chain of any market prices,+including both forward and reverse prices (1 and 2 above), leading from+A to B.+.PP+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 \[dq]gave up\[dq] message visible+in \f[CR]\-\-debug=2\f[R] output).+That limit is currently 1000.+.PP+Amounts for which no suitable market price can be found, are not+converted.+.SS \-\-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 \f[CR]\-\-infer\-market\-prices\f[R] flag to \f[CR]\-V\f[R],+\f[CR]\-X\f[R] or \f[CR]\-\-value\f[R] enables this.+.PP+So for example, \f[CR]hledger bs \-V \-\-infer\-market\-prices\f[R] will+get market prices both from P directives and from transactions.+If both occur on the same day, the P directive takes precedence.+.PP+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 \f[CR]\-\-debug\f[R] or \f[CR]\-\-debug=2\f[R]+to troubleshoot.+.PP+\f[CR]\-\-infer\-market\-prices\f[R] can infer market prices from:+.IP \[bu] 2+multicommodity transactions with explicit prices+(\f[CR]\[at]\f[R]/\f[CR]\[at]\[at]\f[R])+.IP \[bu] 2+multicommodity transactions with implicit prices (no \f[CR]\[at]\f[R],+two commodities, unbalanced).+(With these, the order of postings matters.+\f[CR]hledger print \-x\f[R] can be useful for troubleshooting.)+.IP \[bu] 2+multicommodity transactions with equity postings, if cost is inferred+with \f[CR]\-\-infer\-costs\f[R].+.PP+There is a limitation (bug) currently: when a valuation commodity is not+specified, prices inferred with \f[CR]\-\-infer\-market\-prices\f[R] do+not help select a default valuation commodity, as \f[CR]P\f[R] prices+would.+So conversion might not happen because no valuation commodity was+detected (\f[CR]\-\-debug=2\f[R] will show this).+To be safe, specify the valuation commmodity, eg:+.IP \[bu] 2+\f[CR]\-X EUR \-\-infer\-market\-prices\f[R], not+\f[CR]\-V \-\-infer\-market\-prices\f[R]+.IP \[bu] 2+\f[CR]\-\-value=then,EUR \-\-infer\-market\-prices\f[R], not+\f[CR]\-\-value=then \-\-infer\-market\-prices\f[R]+.PP+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.)+.IP+.EX+2022\-01\-01 Positive Unit prices+    a        A 1+    b        B \-1 \[at] A 1++2022\-01\-01 Positive Total prices+    a        A 1+    b        B \-1 \[at]\[at] A 1+++2022\-01\-02 Negative unit prices+    a        A 1+    b        B 1 \[at] A \-1++2022\-01\-02 Negative total prices+    a        A 1+    b        B 1 \[at]\[at] A \-1+++2022\-01\-03 Double Negative unit prices+    a        A \-1+    b        B \-1 \[at] A \-1++2022\-01\-03 Double Negative total prices+    a        A \-1+    b        B \-1 \[at]\[at] A \-1+.EE+.PP+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:+.IP+.EX+$ 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+.EE+.SS Valuation commodity+\f[B]When you specify a valuation commodity (\f[CB]\-X COMM\f[B] or+\f[CB]\-\-value TYPE,COMM\f[B]):\f[R]+.PD 0+.P+.PD+hledger will convert all amounts to COMM, wherever it can find a+suitable market price (including by reversing or chaining prices).+.PP+\f[B]When you leave the valuation commodity unspecified (\f[CB]\-V\f[B]+or \f[CB]\-\-value TYPE\f[B]):\f[R]+.PD 0+.P+.PD+For each commodity A, hledger picks a default valuation commodity as+follows, in this order of preference:+.IP "1." 3+The price commodity from the latest P\-declared market price for A on or+before valuation date.+.IP "2." 3+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.)+.IP "3." 3+If there are no P directives at all (any commodity or date) and the+\f[CR]\-\-infer\-market\-prices\f[R] flag is used: the price commodity+from the latest transaction\-inferred price for A on or before valuation+date.+.PP+This means:+.IP \[bu] 2+If you have P directives, they determine which commodities+\f[CR]\-V\f[R] will convert, and to what.+.IP \[bu] 2+If you have no P directives, and use the+\f[CR]\-\-infer\-market\-prices\f[R] flag, costs determine it.+.PP+Amounts for which no valuation commodity can be found are not converted.+.SS \-\-value: Flexible valuation+\f[CR]\-V\f[R] and \f[CR]\-X\f[R] are special cases of the more general+\f[CR]\-\-value\f[R] option:+.IP+.EX+ \-\-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+.EE+.PP+The TYPE part selects cost or value and valuation date:+.TP+\f[CR]\-\-value=then\f[R]+Convert amounts to their value in the default valuation commodity, using+market prices on each posting\[aq]s date.+.TP+\f[CR]\-\-value=end\f[R]+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\[aq]s end date); or in multiperiod reports, market prices on+the last day of each subperiod.+.TP+\f[CR]\-\-value=now\f[R]+Convert amounts to their value in the default valuation commodity using+current market prices (as of when report is generated).+.TP+\f[CR]\-\-value=YYYY\-MM\-DD\f[R]+Convert amounts to their value in the default valuation commodity using+market prices on this date.+.PP+To select a different valuation commodity, add the optional+\f[CR],COMM\f[R] part: a comma, then the target commodity\[aq]s symbol.+Eg: \f[B]\f[CB]\-\-value=now,EUR\f[B]\f[R].+hledger will do its best to convert amounts to this commodity, deducing+market prices as described above.+.SS Valuation examples+Here are some quick examples of \f[CR]\-V\f[R]:+.IP+.EX+; 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+.EE+.PP+How many euros do I have ?+.IP+.EX+$ hledger \-f t.j bal \-N euros+                €100  assets:euros+.EE+.PP+What are they worth at end of nov 3 ?+.IP+.EX+$ hledger \-f t.j bal \-N euros \-V \-e 2016/11/4+             $110.00  assets:euros+.EE+.PP+What are they worth after 2016/12/21 ?+(no report end date specified, defaults to today)+.IP+.EX+$ hledger \-f t.j bal \-N euros \-V+             $103.00  assets:euros+.EE+.PP+Here are some examples showing the effect of \f[CR]\-\-value\f[R], as+seen with \f[CR]print\f[R]:+.IP+.EX+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 \[at] 5 B++2000\-02\-01+  (a)      1 A \[at] 6 B++2000\-03\-01+  (a)      1 A \[at] 7 B+.EE+.PP+Show the cost of each posting:+.IP+.EX+$ hledger \-f\- print \-\-cost+2000\-01\-01+    (a)             5 B++2000\-02\-01+    (a)             6 B++2000\-03\-01+    (a)             7 B+.EE+.PP+Show the value as of the last day of the report period (2000\-02\-29):+.IP+.EX+$ hledger \-f\- print \-\-value=end date:2000/01\-2000/03+2000\-01\-01+    (a)             2 B++2000\-02\-01+    (a)             2 B+.EE+.PP+With no report period specified, that shows the value as of the last day+of the journal (2000\-03\-01):+.IP+.EX+$ hledger \-f\- print \-\-value=end+2000\-01\-01+    (a)             3 B++2000\-02\-01+    (a)             3 B++2000\-03\-01+    (a)             3 B+.EE+.PP+Show the current value (the 2000\-04\-01 price is still in effect+today):+.IP+.EX+$ hledger \-f\- print \-\-value=now+2000\-01\-01+    (a)             4 B++2000\-02\-01+    (a)             4 B++2000\-03\-01+    (a)             4 B+.EE+.PP+Show the value on 2000/01/15:+.IP+.EX+$ 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+.EE+.SS Interaction of valuation and queries+When matching postings based on queries in the presence of valuation,+the following happens:+.IP "1." 3+The query is separated into two parts:+.RS 4+.IP "1." 3+the currency (\f[CR]cur:\f[R]) or amount (\f[CR]amt:\f[R]).+.IP "2." 3+all other parts.+.RE+.IP "2." 3+The postings are matched to the currency and amount queries based on+pre\-valued amounts.+.IP "3." 3+Valuation is applied to the postings.+.IP "4." 3+The postings are matched to the other parts of the query based on+post\-valued amounts.+.PP+Related: #1625+.SS Effect of valuation on reports+Here is a reference for how valuation is supposed to affect each part of+hledger\[aq]s reports.+(It\[aq]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.+.PP+First, a quick glossary:+.TP+\f[I]cost\f[R]+calculated using price(s) recorded in the transaction(s).+.TP+\f[I]value\f[R]+market value using available market price declarations, or the unchanged+amount if no conversion rate can be found.+.TP+\f[I]report start\f[R]+the first day of the report period specified with \-b or \-p or date:,+otherwise today.+.TP+\f[I]report or journal start\f[R]+the first day of the report period specified with \-b or \-p or date:,+otherwise the earliest transaction date in the journal, otherwise today.+.TP+\f[I]report end\f[R]+the last day of the report period specified with \-e or \-p or date:,+otherwise today.+.TP+\f[I]report or journal end\f[R]+the last day of the report period specified with \-e or \-p or date:,+otherwise the latest transaction date in the journal, otherwise today.+.TP+\f[I]report interval\f[R]+a flag (\-D/\-W/\-M/\-Q/\-Y) or period expression that activates the+report\[aq]s multi\-period mode (whether showing one or many+subperiods).+.PP+.TS+tab(@);+lw(9.5n) lw(11.8n) lw(12.0n) lw(17.2n) lw(12.0n) lw(7.4n).+T{+Report type+T}@T{+\f[CR]\-B\f[R], \f[CR]\-\-cost\f[R]+T}@T{+\f[CR]\-V\f[R], \f[CR]\-X\f[R]+T}@T{+\f[CR]\-\-value=then\f[R]+T}@T{+\f[CR]\-\-value=end\f[R]+T}@T{+\f[CR]\-\-value=DATE\f[R], \f[CR]\-\-value=now\f[R]+T}+_+T{+\f[B]print\f[R]+T}@T{+T}@T{+T}@T{+T}@T{+T}@T{+T}+T{+posting amounts+T}@T{+cost+T}@T{+value at report end or today+T}@T{+value at posting date+T}@T{+value at report or journal end+T}@T{+value at DATE/today+T}+T{+balance assertions/assignments+T}@T{+unchanged+T}@T{+unchanged+T}@T{+unchanged+T}@T{+unchanged+T}@T{+unchanged+T}+T{+T}@T{+T}@T{+T}@T{+T}@T{+T}@T{+T}+T{+\f[B]register\f[R]+T}@T{+T}@T{+T}@T{+T}@T{+T}@T{+T}+T{+starting balance (\-H)+T}@T{+cost+T}@T{+value at report or journal end+T}@T{+valued at day each historical posting was made+T}@T{+value at report or journal end+T}@T{+value at DATE/today+T}+T{+starting balance (\-H) with report interval+T}@T{+cost+T}@T{+value at day before report or journal start+T}@T{+valued at day each historical posting was made+T}@T{+value at day before report or journal start+T}@T{+value at DATE/today+T}+T{+posting amounts+T}@T{+cost+T}@T{+value at report or journal end+T}@T{+value at posting date+T}@T{+value at report or journal end+T}@T{+value at DATE/today+T}+T{+summary posting amounts with report interval+T}@T{+summarised cost+T}@T{+value at period ends+T}@T{+sum of postings in interval, valued at interval start+T}@T{+value at period ends+T}@T{+value at DATE/today+T}+T{+running total/average+T}@T{+sum/average of displayed values+T}@T{+sum/average of displayed values+T}@T{+sum/average of displayed values+T}@T{+sum/average of displayed values+T}@T{+sum/average of displayed values+T}+T{+T}@T{+T}@T{+T}@T{+T}@T{+T}@T{+T}+T{+\f[B]balance (bs, bse, cf, is)\f[R]+T}@T{+T}@T{+T}@T{+T}@T{+T}@T{+T}+T{+balance changes+T}@T{+sums of costs+T}@T{+value at report end or today of sums of postings+T}@T{+value at posting date+T}@T{+value at report or journal end of sums of postings+T}@T{+value at DATE/today of sums of postings+T}+T{+budget amounts (\-\-budget)+T}@T{+like balance changes+T}@T{+like balance changes+T}@T{+like balance changes+T}@T{+like balances+T}@T{+like balance changes+T}+T{+grand total+T}@T{+sum of displayed values+T}@T{+sum of displayed values+T}@T{+sum of displayed valued+T}@T{+sum of displayed values+T}@T{+sum of displayed values+T}+T{+T}@T{+T}@T{+T}@T{+T}@T{+T}@T{+T}+T{+\f[B]balance (bs, bse, cf, is) with report interval\f[R]+T}@T{+T}@T{+T}@T{+T}@T{+T}@T{+T}+T{+starting balances (\-H)+T}@T{+sums of costs of postings before report start+T}@T{+value at report start of sums of all postings before report start+T}@T{+sums of values of postings before report start at respective posting+dates+T}@T{+value at report start of sums of all postings before report start+T}@T{+sums of postings before report start+T}+T{+balance changes (bal, is, bs \-\-change, cf \-\-change)+T}@T{+sums of costs of postings in period+T}@T{+same as \-\-value=end+T}@T{+sums of values of postings in period at respective posting dates+T}@T{+balance change in each period, valued at period ends+T}@T{+value at DATE/today of sums of postings+T}+T{+end balances (bal \-H, is \-\-H, bs, cf)+T}@T{+sums of costs of postings from before report start to period end+T}@T{+same as \-\-value=end+T}@T{+sums of values of postings from before period start to period end at+respective posting dates+T}@T{+period end balances, valued at period ends+T}@T{+value at DATE/today of sums of postings+T}+T{+budget amounts (\-\-budget)+T}@T{+like balance changes/end balances+T}@T{+like balance changes/end balances+T}@T{+like balance changes/end balances+T}@T{+like balances+T}@T{+like balance changes/end balances+T}+T{+row totals, row averages (\-T, \-A)+T}@T{+sums, averages of displayed values+T}@T{+sums, averages of displayed values+T}@T{+sums, averages of displayed values+T}@T{+sums, averages of displayed values+T}@T{+sums, averages of displayed values+T}+T{+column totals+T}@T{+sums of displayed values+T}@T{+sums of displayed values+T}@T{+sums of displayed values+T}@T{+sums of displayed values+T}@T{+sums of displayed values+T}+T{+grand total, grand average+T}@T{+sum, average of column totals+T}@T{+sum, average of column totals+T}@T{+sum, average of column totals+T}@T{+sum, average of column totals+T}@T{+sum, average of column totals+T}+T{+T}@T{+T}@T{+T}@T{+T}@T{+T}@T{+T}+.TE+.PP+\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].+If you have installed more add\-on commands, they also will be listed.+.PP+\f[B]Help commands\f[R]+.IP \[bu] 2+help \- show the hledger manual with info/man/pager+.IP \[bu] 2+demo \- show small hledger demos in the terminal+.PP+\f[B]User interface commands\f[R]+.IP \[bu] 2+ui \- (if installed) run hledger\[aq]s terminal UI+.IP \[bu] 2+web \- (if installed) run hledger\[aq]s web UI+.PP+\f[B]Data entry commands\f[R]+.IP \[bu] 2+add \- add transactions using terminal prompts+.IP \[bu] 2+import \- add new transactions from other files, eg CSV files+.PP+\f[B]Basic report commands\f[R]+.IP \[bu] 2+accounts \- show account names+.IP \[bu] 2+codes \- show transaction codes+.IP \[bu] 2+commodities \- show commodity/currency symbols+.IP \[bu] 2+descriptions \- show transaction descriptions+.IP \[bu] 2+files \- show input file paths+.IP \[bu] 2+notes \- show note parts of transaction descriptions+.IP \[bu] 2+payees \- show payee parts of transaction descriptions+.IP \[bu] 2+prices \- show market prices+.IP \[bu] 2+stats \- show journal statistics+.IP \[bu] 2+tags \- show tag names+.PP+\f[B]Standard report commands\f[R]+.IP \[bu] 2+print \- show transactions or export journal data+.IP \[bu] 2+aregister (areg) \- show transactions in a particular account+.IP \[bu] 2+register (reg) \- show postings in one or more accounts & running total+.IP \[bu] 2+balancesheet (bs) \- show assets, liabilities and net worth+.IP \[bu] 2+balancesheetequity (bse) \- show assets, liabilities and equity+.IP \[bu] 2+cashflow (cf) \- show changes in liquid assets+.IP \[bu] 2+incomestatement (is) \- show revenues and expenses+.PP+\f[B]Advanced report commands\f[R]+.IP \[bu] 2+balance (bal) \- show balance changes, end balances, budgets, gains..+.IP \[bu] 2+roi \- show return on investments+.PP+\f[B]Chart commands\f[R]+.IP \[bu] 2+activity \- show bar charts of posting counts per period+.PP+\f[B]Data generation commands\f[R]+.IP \[bu] 2+close \- generate balance\-zeroing/restoring transactions+.IP \[bu] 2+rewrite \- generate auto postings, like print \-\-auto+.PP+\f[B]Maintenance commands\f[R]+.IP \[bu] 2+check \- check for various kinds of error in the data+.IP \[bu] 2+diff \- compare account transactions in two journal files+.IP \[bu] 2+test \- run self tests+.PP+Next, these commands are described in detail.+.SH Help commands+.SS help+Show the hledger user manual with \f[CR]info\f[R], \f[CR]man\f[R], or a+pager.+With a (case insensitive) TOPIC argument, try to open it at that section+heading.+.PP+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.+.PP+By default it chooses the best viewer found in $PATH, trying in this+order: \f[CR]info\f[R], \f[CR]man\f[R], \f[CR]$PAGER\f[R],+\f[CR]less\f[R], \f[CR]more\f[R], stdout.+(If a TOPIC is specified, \f[CR]$PAGER\f[R] and \f[CR]more\f[R] are not+tried.)+You can force the use of info, man, or a pager with the \f[CR]\-i\f[R],+\f[CR]\-m\f[R], or \f[CR]\-p\f[R] flags.+If no viewer can be found, or if running non\-interactively, it just+prints the manual to stdout.+.PP+When using \f[CR]info\f[R], TOPIC can match either the full heading or a+prefix.+If your \f[CR]info \-\-version\f[R] is < 6, you\[aq]ll need to upgrade+it, eg with \[aq]\f[CR]brew install texinfo\f[R]\[aq] on mac.+.PP+When using \f[CR]man\f[R] or \f[CR]less\f[R], TOPIC must match the full+heading.+For a prefix match, you can write \[aq]\f[CR]TOPIC.*\f[R]\[aq].+.PP+Examples+.IP+.EX+$ hledger help \-h                 # show the help command\[aq]s usage+$ hledger help                    # show the manual with info, man or $PAGER+$ hledger help \[aq]time periods\[aq]     # show the manual\[aq]s \[dq]Time periods\[dq] topic+$ hledger help \[aq]time periods\[aq] \-m  # use man, even if info is installed+.EE+.SS demo+Play demos of hledger usage in the terminal, if asciinema is installed.+.PP+Run this command with no argument to list the demos.+To play a demo, write its number or a prefix or substring of its title.+Tips:+.PP+Make your terminal window large enough to see the demo clearly.+.PP+Use the \-s/\-\-speed SPEED option to set your preferred playback speed,+eg \f[CR]\-s4\f[R] to play at 4x original speed or \f[CR]\-s.5\f[R] to+play at half speed.+The default speed is 2x.+.PP+Other asciinema options can be added following a double dash, eg+\f[CR]\-\- \-i.1\f[R] to limit pauses or \f[CR]\-\- \-h\f[R] to list+asciinema\[aq]s other options.+.PP+During playback, several keys are available: SPACE to pause/unpause, .+to step forward (while paused), CTRL\-c quit.+.PP+Examples:+.IP+.EX+$ hledger demo               # list available demos+$ hledger demo 1             # play the first demo at default speed (2x)+$ hledger demo install \-s4   # play the \[dq]install\[dq] demo at 4x speed+.EE+.SH User interface commands+.SS ui+Runs hledger\-ui (if installed).+.SS web+Runs hledger\-web (if installed).+.SH Data entry commands+.SS add+Record new transactions with interactive prompting in the console.+.PP+Many hledger users edit their journals directly with a text editor, or+generate them from CSV.+For more interactive data entry, there is the \f[CR]add\f[R] 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 \f[CR]import\f[R]).+.PP+To use it, just run \f[CR]hledger add\f[R] and follow the prompts.+You can add as many transactions as you like; when you are finished,+enter \f[CR].\f[R] or press control\-d or control\-c to exit.+.PP+Features:+.IP \[bu] 2+add tries to provide useful defaults, using the most similar (by+description) recent transaction (filtered by the query, if any) as a+template.+.IP \[bu] 2+You can also set the initial defaults with command line arguments.+.IP \[bu] 2+Readline\-style edit keys can be used during data entry.+.IP \[bu] 2+The tab key will auto\-complete whenever possible \- accounts,+payees/descriptions, dates (\f[CR]yesterday\f[R], \f[CR]today\f[R],+\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.+.IP \[bu] 2+If you make a mistake, enter \f[CR]<\f[R] at any prompt to go one step+backward.+.IP \[bu] 2+Input prompts are displayed in a different colour when the terminal+supports it.+.PP+Notes:+.IP \[bu] 2+If you enter a number with no commodity symbol, and you have declared a+default commodity with a \f[CR]D\f[R] directive, you might expect+\f[CR]add\f[R] to add this symbol for you.+It does not do this; we assume that if you are using a \f[CR]D\f[R]+directive you prefer not to see the commodity symbol repeated on amounts+in the journal.+.PP+Examples:+.IP \[bu] 2+Record new transactions, saving to the default journal file:+.RS 2+.PP+\f[CR]hledger add\f[R]+.RE+.IP \[bu] 2+Add transactions to 2024.journal, but also load 2023.journal for+completions:+.RS 2+.PP+\f[CR]hledger add \-\-file 2024.journal \-\-file 2023.journal\f[R]+.RE+.IP \[bu] 2+Provide answers for the first four prompts:+.RS 2+.PP+\f[CR]hledger add today \[aq]best buy\[aq] expenses:supplies \[aq]$20\[aq]\f[R]+.RE+.PP+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.+.PP+This command detects new transactions in each FILE argument since it was+last run, and appends them to the main journal.+.PP+Or with \f[CR]\-\-dry\-run\f[R], it just print the transactions that+would be added.+.PP+Or with \f[CR]\-\-catchup\f[R], it just marks all of the FILEs\[aq]+current transactions as already imported.+.PP+This is one of the few hledger commands that writes to the journal file+(see also \f[CR]add\f[R]).+It only appends; existing data will not be changed.+.PP+The input files are specified as arguments, so to import one or more CSV+files to your main journal, you will run+\f[CR]hledger import bank.csv\f[R] or perhaps+\f[CR]hledger import *.csv\f[R].+.PP+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.+.SS Date skipping+\f[CR]import\f[R] 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\[aq]s CSV includes the last three months of data, you+can download and \f[CR]import\f[R] it every month (or week, or day) and+only the new transactions will be imported each time.+.PP+It works as follows: for each imported \f[CR]FILE\f[R],+.IP \[bu] 2+It tries to read the latest date previously seen, from+\f[CR].latest.FILE\f[R] in the same directory+.IP \[bu] 2+Then it processes \f[CR]FILE\f[R], ignoring transactions on or before+that date+.PP+And after a successful import, unless \f[CR]\-\-dry\-run\f[R] was used,+it updates the \f[CR].latest.FILE\f[R](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:+.IP "1." 3+the name of the input file is stable across successive downloads+.IP "2." 3+new items always have the newest dates+.IP "3." 3+item dates are stable across downloads+.IP "4." 3+the order of same\-date items is stable across downloads.+.PP+Tips:+.IP \[bu] 2+To help ensure a stable file name, remember you can use a CSV rules file+as an input file.+.IP \[bu] 2+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\[aq]s harmless.)+.PP+Note this is just one kind of \[dq]deduplication\[dq]: not reprocessing+the same dates across successive runs.+\f[CR]import\f[R] doesn\[aq]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.)+.PP+Here\[aq]s a situation where you need to run \f[CR]import\f[R] with+care: say you download but forget to import \f[CR]bank.1.csv\f[R], and a+week later you download \f[CR]bank.2.csv\f[R] with some overlapping+data.+You should not process both of these as a single import+(\f[CR]hledger import bank.1.csv bank.2.csv\f[R]), because the+overlapping transactions would not be deduplicated.+Instead, import one file at a time, using the same filename each time:+.IP+.EX+$ mv bank.1.csv bank.csv; hledger import bank.csv+$ mv bank.2.csv bank.csv; hledger import bank.csv+.EE+.PP+Normally you don\[aq]t need to think about \f[CR].latest.*\f[R] 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 \f[CR]YYYY\-MM\-DD\f[R] date,+optionally repeated on multiple lines, meaning \[dq]I have seen the+transactions before this date, and this many of them on this date\[dq].+.PP+\f[CR]hledger print \-\-new\f[R] also uses and updates these+\f[CR].latest.*\f[R] files, but it is less often used.+.PP+Related: CSV > Working with CSV > Deduplicating, importing.+.SS Import testing+With \f[CR]\-\-dry\-run\f[R], 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:+.IP+.EX+$ hledger import \-\-dry bank.csv | hledger \-f\- \-I print unknown+.EE+.PP+or (live updating):+.IP+.EX+$ ls bank.csv* | entr bash \-c \[aq]echo ====; hledger import \-\-dry bank.csv | hledger \-f\- \-I print unknown\[aq]+.EE+.PP+Note: when importing from multiple files at once, it\[aq]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.+.SS Importing balance assignments+Entries added by import will have their posting amounts made explicit+(like \f[CR]hledger print \-x\f[R]).+This means that any balance assignments in imported files must be+evaluated; but, imported files don\[aq]t get to see the main file\[aq]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:+.IP+.EX+$ hledger print IMPORTFILE [\-\-new] >> $LEDGER_FILE+.EE+.PP+(If you think import should leave amounts implicit like print does,+please test it and send a pull request.)+.SS Import and commodity styles+Amounts in entries added by import will be formatted according to the+journal\[aq]s canonical commodity styles, as declared by+\f[CR]commodity\f[R] directives or inferred from the journal\[aq]s+amounts.+.PP+Related: CSV > Amount decimal places.+.SH Basic report commands+.SS accounts+List account names.+.PP+This command lists account names.+By default it shows all known accounts, either used in transactions or+declared with account directives.+.PP+With query arguments, only matched account names and account names+referenced by matched postings are shown.+.PP+Or it can show just the used accounts+(\f[CR]\-\-used\f[R]/\f[CR]\-u\f[R]), the declared accounts+(\f[CR]\-\-declared\f[R]/\f[CR]\-d\f[R]), the accounts declared but not+used (\f[CR]\-\-unused\f[R]), the accounts used but not declared+(\f[CR]\-\-undeclared\f[R]), or the first account matched by an account+name pattern, if any (\f[CR]\-\-find\f[R]).+.PP+It shows a flat list by default.+With \f[CR]\-\-tree\f[R], it uses indentation to show the account+hierarchy.+In flat mode you can add \f[CR]\-\-drop N\f[R] to omit the first few+account name components.+Account names can be depth\-clipped with \f[CR]depth:N\f[R] or+\f[CR]\-\-depth N\f[R] or \f[CR]\-N\f[R].+.PP+With \f[CR]\-\-types\f[R], it also shows each account\[aq]s type, if+it\[aq]s known.+(See Declaring accounts > Account types.)+.PP+With \f[CR]\-\-positions\f[R], it also shows the file and line number of+each account\[aq]s declaration, if any, and the account\[aq]s overall+declaration order; these may be useful when troubleshooting account+display order.+.PP+With \f[CR]\-\-directives\f[R], it adds the \f[CR]account\f[R] keyword,+showing valid account directives which can be pasted into a journal+file.+This is useful together with \f[CR]\-\-undeclared\f[R] when updating+your account declarations to satisfy \f[CR]hledger check accounts\f[R].+.PP+The \f[CR]\-\-find\f[R] flag can be used to look up a single account+name, in the same way that the \f[CR]aregister\f[R] command does.+It returns the alphanumerically\-first matched account name, or if none+can be found, it fails with a non\-zero exit code.+.PP+Examples:+.IP+.EX+$ hledger accounts+assets:bank:checking+assets:bank:saving+assets:cash+expenses:food+expenses:supplies+income:gifts+income:salary+liabilities:debts+.EE+.IP+.EX+$ hledger accounts \-\-undeclared \-\-directives >> $LEDGER_FILE+$ hledger check accounts+.EE+.SS codes+List the codes seen in transactions, in the order parsed.+.PP+This command prints the value of each transaction\[aq]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.+.PP+Transactions aren\[aq]t required to have a code, and missing or empty+codes will not be shown by default.+With the \f[CR]\-E\f[R]/\f[CR]\-\-empty\f[R] flag, they will be printed+as blank lines.+.PP+You can add a query to select a subset of transactions.+.PP+Examples:+.IP+.EX+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+.EE+.IP+.EX+$ hledger codes+123+124+126+.EE+.IP+.EX+$ hledger codes \-E+123+124++126+.EE+.SS commodities+List all commodity/currency symbols used or declared in the journal.+.SS descriptions+List the unique descriptions that appear in transactions.+.PP+This command lists the unique descriptions that appear in transactions,+in alphabetic order.+You can add a query to select a subset of transactions.+.PP+Example:+.IP+.EX+$ hledger descriptions+Store Name+Gas Station | Petrol+Person A+.EE+.SS files+List all files included in the journal.+With a REGEX argument, only file names matching the regular expression+(case sensitive) are shown.+.SS notes+List the unique notes that appear in transactions.+.PP+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).+.PP+Example:+.IP+.EX+$ hledger notes+Petrol+Snacks+.EE+.SS payees+List the unique payee/payer names that appear in transactions.+.PP+This command lists unique payee/payer names which have been declared+with payee directives (\-\-declared), used in transaction descriptions+(\-\-used), or both (the default).+.PP+The payee/payer is the part of the transaction description before a |+character (or if there is no |, the whole description).+.PP+You can add query arguments to select a subset of transactions.+This implies \-\-used.+.PP+Example:+.IP+.EX+$ hledger payees+Store Name+Gas Station+Person A+.EE+.SS 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.+.PP+Price amounts are always displayed with their full precision, except for+reverse prices which are limited to 8 decimal digits.+.PP+Prices can be filtered by a date:, cur: or amt: query.+.PP+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.+.SS stats+Show journal and performance statistics.+.PP+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.+.PP+The default output is fairly impersonal, though it reveals the main file+name.+With \f[CR]\-v/\-\-verbose\f[R], more details are shown, like file+paths, included files, and commodity names.+.PP+It also shows some run time statistics:+.IP \[bu] 2+elapsed time+.IP \[bu] 2+throughput: the number of transactions processed per second+.IP \[bu] 2+live: the peak memory in use by the program to do its work+.IP \[bu] 2+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.+.PP+The \f[CR]stats\f[R] command\[aq]s run time is similar to that of a+balance report.+.PP+Example:+.IP+.EX+$ 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+.EE+.PP+This command supports the \-o/\-\-output\-file option (but not+\-O/\-\-output\-format).+.SS tags+List the tags used in the journal, or their values.+.PP+This command lists the tag names used in the journal, whether on+transactions, postings, or account declarations.+.PP+With a TAGREGEX argument, only tag names matching this regular+expression (case insensitive, infix matched) are shown.+.PP+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.+.PP+With the \-\-values flag, the tags\[aq] unique non\-empty values are+listed instead.+With \-E/\-\-empty, blank/empty values are also shown.+.PP+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.)+.PP+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.+.SH Standard report commands+.SS print+Show full journal entries, representing transactions.+.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+date).+.PP+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.+.PP+Eg:+.IP+.EX+$ 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+.EE+.SS 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.+.PP+You can use the \f[CR]\-x\f[R]/\f[CR]\-\-explicit\f[R] 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.+\f[CR]\-x\f[R] is also implied by using any of+\f[CR]\-B\f[R],\f[CR]\-V\f[R],\f[CR]\-X\f[R],\f[CR]\-\-value\f[R].+.PP+The \f[CR]\-x\f[R]/\f[CR]\-\-explicit\f[R] 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.+.SS 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).+.PP+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.+.PP+With the \f[CR]\-\-round\f[R] (\f[I]Added in 1.32\f[R]) option,+\f[CR]print\f[R] will try increasingly hard to display decimal digits+according to the commodity display styles:+.IP \[bu] 2+\f[CR]\-\-round=none\f[R] show amounts with original precisions+(default)+.IP \[bu] 2+\f[CR]\-\-round=soft\f[R] add/remove decimal zeros in amounts (except+costs)+.IP \[bu] 2+\f[CR]\-\-round=hard\f[R] round amounts (except costs), possibly hiding+significant digits+.IP \[bu] 2+\f[CR]\-\-round=all\f[R] round all amounts and costs+.PP+\f[CR]soft\f[R] is good for non\-lossy cleanup, formatting amounts more+consistently where it\[aq]s safe to do so.+.PP+\f[CR]hard\f[R] and \f[CR]all\f[R] can cause \f[CR]print\f[R] to show+invalid unbalanced journal entries; they may be useful eg for stronger+cleanup, with manual fixups when needed.+.SS print parseability+print\[aq]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 \f[CR]expr:\f[R] queries now):+.IP+.EX+# 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+.EE+.PP+There are some situations where print\[aq]s output can become+unparseable:+.IP \[bu] 2+Value reporting affects posting amounts but not balance assertion or+balance assignment amounts, potentially causing those to fail.+.IP \[bu] 2+Auto postings can generate postings with too many missing amounts.+.IP \[bu] 2+Account aliases can generate bad account names.+.SS print, other features+With \f[CR]\-B\f[R]/\f[CR]\-\-cost\f[R], amounts with costs are shown+converted to cost.+.PP+With \f[CR]\-\-new\f[R], print shows only transactions it has not seen+on a previous run.+This uses the same deduplication system as the \f[CR]import\f[R]+command.+(See import\[aq]s docs for details.)+.PP+With \f[CR]\-m DESC\f[R]/\f[CR]\-\-match=DESC\f[R], 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.+.SS print output format+This command also supports the output destination and output format+options The output formats supported are \f[CR]txt\f[R],+\f[CR]beancount\f[R] (\f[I]Added in 1.32\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+\f[CR]sql\f[R].+.PP+The \f[CR]beancount\f[R] format tries to produce Beancount\-compatible+output, as follows:+.IP \[bu] 2+Transaction and postings with unmarked status are converted to cleared+(\f[CR]*\f[R]) status.+.IP \[bu] 2+Transactions\[aq] payee and note are backslash\-escaped and+double\-quote\-escaped and wrapped in double quotes.+.IP \[bu] 2+Transaction tags are copied to Beancount #tag format.+.IP \[bu] 2+Commodity symbols are converted to upper case, and a small number of+currency symbols like \f[CR]$\f[R] are converted to the corresponding+currency names.+.IP \[bu] 2+Account name parts are capitalised and unsupported characters are+replaced with \f[CR]\-\f[R].+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 \f[CR]\-\-alias\f[R] options to bring your accounts into+compliance.)+.IP \[bu] 2+An \f[CR]open\f[R] directive is generated for each account used, on the+earliest transaction date.+.PP+Some limitations:+.IP \[bu] 2+Balance assertions are removed.+.IP \[bu] 2+Balance assignments become missing amounts.+.IP \[bu] 2+Virtual and balanced virtual postings become regular postings.+.IP \[bu] 2+Directives are not converted.+.PP+Here\[aq]s an example of print\[aq]s CSV output:+.IP+.EX+$ hledger print \-Ocsv+\[dq]txnidx\[dq],\[dq]date\[dq],\[dq]date2\[dq],\[dq]status\[dq],\[dq]code\[dq],\[dq]description\[dq],\[dq]comment\[dq],\[dq]account\[dq],\[dq]amount\[dq],\[dq]commodity\[dq],\[dq]credit\[dq],\[dq]debit\[dq],\[dq]posting\-status\[dq],\[dq]posting\-comment\[dq]+\[dq]1\[dq],\[dq]2008/01/01\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]income\[dq],\[dq]\[dq],\[dq]assets:bank:checking\[dq],\[dq]1\[dq],\[dq]$\[dq],\[dq]\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq]+\[dq]1\[dq],\[dq]2008/01/01\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]income\[dq],\[dq]\[dq],\[dq]income:salary\[dq],\[dq]\-1\[dq],\[dq]$\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq]+\[dq]2\[dq],\[dq]2008/06/01\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]gift\[dq],\[dq]\[dq],\[dq]assets:bank:checking\[dq],\[dq]1\[dq],\[dq]$\[dq],\[dq]\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq]+\[dq]2\[dq],\[dq]2008/06/01\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]gift\[dq],\[dq]\[dq],\[dq]income:gifts\[dq],\[dq]\-1\[dq],\[dq]$\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq]+\[dq]3\[dq],\[dq]2008/06/02\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]save\[dq],\[dq]\[dq],\[dq]assets:bank:saving\[dq],\[dq]1\[dq],\[dq]$\[dq],\[dq]\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq]+\[dq]3\[dq],\[dq]2008/06/02\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]save\[dq],\[dq]\[dq],\[dq]assets:bank:checking\[dq],\[dq]\-1\[dq],\[dq]$\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq]+\[dq]4\[dq],\[dq]2008/06/03\[dq],\[dq]\[dq],\[dq]*\[dq],\[dq]\[dq],\[dq]eat & shop\[dq],\[dq]\[dq],\[dq]expenses:food\[dq],\[dq]1\[dq],\[dq]$\[dq],\[dq]\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq]+\[dq]4\[dq],\[dq]2008/06/03\[dq],\[dq]\[dq],\[dq]*\[dq],\[dq]\[dq],\[dq]eat & shop\[dq],\[dq]\[dq],\[dq]expenses:supplies\[dq],\[dq]1\[dq],\[dq]$\[dq],\[dq]\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq]+\[dq]4\[dq],\[dq]2008/06/03\[dq],\[dq]\[dq],\[dq]*\[dq],\[dq]\[dq],\[dq]eat & shop\[dq],\[dq]\[dq],\[dq]assets:cash\[dq],\[dq]\-2\[dq],\[dq]$\[dq],\[dq]2\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq]+\[dq]5\[dq],\[dq]2008/12/31\[dq],\[dq]\[dq],\[dq]*\[dq],\[dq]\[dq],\[dq]pay off\[dq],\[dq]\[dq],\[dq]liabilities:debts\[dq],\[dq]1\[dq],\[dq]$\[dq],\[dq]\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq]+\[dq]5\[dq],\[dq]2008/12/31\[dq],\[dq]\[dq],\[dq]*\[dq],\[dq]\[dq],\[dq]pay off\[dq],\[dq]\[dq],\[dq]assets:bank:checking\[dq],\[dq]\-1\[dq],\[dq]$\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq]+.EE+.IP \[bu] 2+There is one CSV record per posting, with the parent transaction\[aq]s+fields repeated.+.IP \[bu] 2+The \[dq]txnidx\[dq] (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.)+.IP \[bu] 2+The amount is separated into \[dq]commodity\[dq] (the symbol) and+\[dq]amount\[dq] (numeric quantity) fields.+.IP \[bu] 2+The numeric amount is repeated in either the \[dq]credit\[dq] or+\[dq]debit\[dq] 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.)+.SS aregister+(areg)+.PP+Show the transactions and running balances in one account, with each+transaction on one line.+.PP+\f[CR]aregister\f[R] 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 (\f[CR]\-\-historical\f[R] mode is always on).+.PP+This is a more \[dq]real world\[dq], bank\-like view than the+\f[CR]register\f[R] command (which shows individual postings, possibly+from multiple accounts, not necessarily in historical mode).+As a quick rule of thumb: \- use \f[CR]aregister\f[R] for reviewing and+reconciling real\-world asset/liability accounts \- use+\f[CR]register\f[R] for reviewing detailed revenues/expenses.+.PP+\f[CR]aregister\f[R] 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.+.PP+When there are multiple matches, the alphabetically\-first choice can be+surprising; eg if you have \f[CR]assets:per:checking 1\f[R] and+\f[CR]assets:biz:checking 2\f[R] accounts,+\f[CR]hledger areg checking\f[R] would select+\f[CR]assets:biz:checking 2\f[R].+It\[aq]s just a convenience to save typing, so if in doubt, write the+full account name, or a distinctive substring that matches uniquely.+.PP+Transactions involving subaccounts of this account will also be shown.+\f[CR]aregister\f[R] ignores depth limits, so its final total will+always match a balance report with similar arguments.+.PP+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\[aq]s real\-world running balance.+.PP+An example: this shows the transactions and historical running balance+during july, in the first account whose name contains+\[dq]checking\[dq]:+.IP+.EX+$ hledger areg checking date:jul+.EE+.PP+Each \f[CR]aregister\f[R] line item shows:+.IP \[bu] 2+the transaction\[aq]s date (or the relevant posting\[aq]s date if+different, see below)+.IP \[bu] 2+the names of all the other account(s) involved in this transaction+(probably abbreviated)+.IP \[bu] 2+the total change to this account\[aq]s balance from this transaction+.IP \[bu] 2+the account\[aq]s historical running balance after this transaction.+.PP+Transactions making a net change of zero are not shown by default; add+the \f[CR]\-E/\-\-empty\f[R] flag to show them.+.PP+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 \f[CR]\-\-align\-all\f[R] flag.+.PP+This command also supports the output destination and output format+options.+The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],+\f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), and \f[CR]json\f[R].+.SS 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\[aq]s postings may be within the report+period.+To resolve this, aregister shows the earliest of the transaction\[aq]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\[aq]s last posting) be inaccurate.+Use \f[CR]register \-H\f[R] if you need to see the individual postings.+.PP+There is also a \f[CR]\-\-txn\-dates\f[R] flag, which filters strictly+by transaction date, ignoring posting dates.+This too can cause an inaccurate running balance.+.SS register+(reg)+.PP+Show postings and their running total.+.PP+The register command displays matched postings, across all accounts, in+date order, with their running total or running historical balance.+(See also the \f[CR]aregister\f[R] command, which shows matched+transactions in a specific account.)+.PP+register normally shows line per posting, but note that multi\-commodity+amounts will occupy multiple lines (one line per commodity).+.PP+It is typically used with a query selecting a particular account, to see+that account\[aq]s activity:+.IP+.EX+$ 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+.EE+.PP+With \f[CR]\-\-date2\f[R], it shows and sorts by secondary date instead.+.PP+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 \f[CR]\-\-align\-all\f[R] flag.+.PP+The \f[CR]\-\-historical\f[R]/\f[CR]\-H\f[R] 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:+.IP+.EX+$ 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+.EE+.PP+The \f[CR]\-\-depth\f[R] option limits the amount of sub\-account detail+displayed.+.PP+The \f[CR]\-\-average\f[R]/\f[CR]\-A\f[R] 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 \f[CR]\-\-empty\f[R] (see below).+It is affected by \f[CR]\-\-historical\f[R].+It works best when showing just one account and one commodity.+.PP+The \f[CR]\-\-related\f[R]/\f[CR]\-r\f[R] flag shows the \f[I]other\f[R]+postings in the transactions of the postings which would normally be+shown.+.PP+The \f[CR]\-\-invert\f[R] flag negates all amounts.+For example, it can be used on an income account where amounts are+normally displayed as negative numbers.+It\[aq]s also useful to show postings on the checking account together+with the related account:+.IP+.EX+$ hledger register \-\-related \-\-invert assets:checking+.EE+.PP+With a reporting interval, register shows summary postings, one per+interval, aggregating the postings to each account:+.IP+.EX+$ hledger register \-\-monthly income+2008/01                 income:salary                          $\-1          $\-1+2008/06                 income:gifts                           $\-1          $\-2+.EE+.PP+Periods with no activity, and summary postings with a zero amount, are+not shown by default; use the \f[CR]\-\-empty\f[R]/\f[CR]\-E\f[R] flag+to see them:+.IP+.EX+$ 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+.EE+.PP+Often, you\[aq]ll want to see just one line per interval.+The \f[CR]\-\-depth\f[R] option helps with this, causing subaccounts to+be aggregated:+.IP+.EX+$ hledger register \-\-monthly assets \-\-depth 1h+2008/01                 assets                                  $1           $1+2008/06                 assets                                 $\-1            0+2008/12                 assets                                 $\-1          $\-1+.EE+.PP+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.+.PP+With \f[CR]\-m DESC\f[R]/\f[CR]\-\-match=DESC\f[R], 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.+.SS Custom register output+register uses the full terminal width by default, except on windows.+You can override this by setting the \f[CR]COLUMNS\f[R] environment+variable (not a bash shell variable) or by using the+\f[CR]\-\-width\f[R]/\f[CR]\-w\f[R] option.+.PP+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\[aq]s argument, comma\-separated: \f[CR]\-\-width W,D\f[R] .+Here\[aq]s a diagram (won\[aq]t display correctly in \-\-help):+.IP+.EX+<\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- width (W) \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\->+date (10)  description (D)       account (W\-41\-D)     amount (12)   balance (12)+DDDDDDDDDD dddddddddddddddddddd  aaaaaaaaaaaaaaaaaaa  AAAAAAAAAAAA  AAAAAAAAAAAA+.EE+.PP+and some examples:+.IP+.EX+$ hledger reg                     # use terminal width (or 80 on windows)+$ hledger reg \-w 100              # use width 100+$ COLUMNS=100 hledger reg         # set with one\-time environment variable+$ export COLUMNS=100; hledger reg # set till session end (or window resize)+$ hledger reg \-w 100,40           # set overall width 100, description width 40+$ hledger reg \-w $COLUMNS,40      # use terminal width, & description width 40+.EE+.PP+This command also supports the output destination and output format+options The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],+\f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), and \f[CR]json\f[R].+.SS balancesheet+(bs)+.PP+Show the end balances in asset and liability accounts.+Amounts are shown with normal positive sign, as in conventional+financial statements.+.PP+This command displays a balance sheet, showing historical ending+balances of asset and liability accounts.+(To see equity as well, use the balancesheetequity command.)+.PP+Accounts declared with the \f[CR]Asset\f[R], \f[CR]Cash\f[R] or+\f[CR]Liability\f[R] type are shown (see account types).+Or if no such accounts are declared, it shows top\-level accounts named+\f[CR]asset\f[R] or \f[CR]liability\f[R] (case insensitive, plurals+allowed) and their subaccounts.+.PP+Example:+.IP+.EX+$ 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 +.EE+.PP+This command is a higher\-level variant of the \f[CR]balance\f[R]+command, and supports many of that command\[aq]s features, such as+multi\-period reports.+It is similar to \f[CR]hledger balance \-H assets liabilities\f[R], but+with smarter account detection, and liabilities displayed with their+sign flipped.+.PP+This command also supports the output destination and output format+options The output formats supported are \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]html\f[R], and+\f[CR]json\f[R].+.SS balancesheetequity+(bse)+.PP+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.+.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+account types).+Or if no such accounts are declared, it shows top\-level accounts named+\f[CR]asset\f[R], \f[CR]liability\f[R] or \f[CR]equity\f[R] (case+insensitive, plurals allowed) and their subaccounts.+.PP+Example:+.IP+.EX+$ 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 +.EE+.PP+This command is a higher\-level variant of the \f[CR]balance\f[R]+command, and supports many of that command\[aq]s features, such as+multi\-period reports.+It is similar to+\f[CR]hledger balance \-H assets liabilities equity\f[R], but with+smarter account detection, and liabilities/equity displayed with their+sign flipped.+.PP+This report is the easiest way to see if the accounting equation (A+L+E+= 0) is satisfied (after you have done a \f[CR]close \-\-retain\f[R] to+merge revenues and expenses with equity, and perhaps added+\f[CR]\-\-infer\-equity\f[R] to balance your commodity conversions).+.PP+This command also supports the output destination and output format+options The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],+\f[CR]tsv\f[R], \f[CR]html\f[R], and \f[CR]json\f[R].+.SS cashflow+(cf)+.PP+This command displays a (simple) cashflow statement, showing the inflows+and outflows affecting \[dq]cash\[dq] (ie, liquid, easily convertible)+assets.+Amounts are shown with normal positive sign, as in conventional+financial statements.+.PP+This report shows accounts declared with the \f[CR]Cash\f[R] type (see+account types).+Or if no such accounts are declared, it shows accounts+.IP \[bu] 2+under a top\-level account named \f[CR]asset\f[R] (case insensitive,+plural allowed)+.IP \[bu] 2+whose name contains some variation of \f[CR]cash\f[R], \f[CR]bank\f[R],+\f[CR]checking\f[R] or \f[CR]saving\f[R].+.PP+More precisely: all accounts matching this case insensitive regular+expression:+.PP+\f[CR]\[ha]assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$)\f[R]+.PP+and their subaccounts.+.PP+An example cashflow report:+.IP+.EX+$ hledger cashflow+Cashflow Statement 2008++                    || 2008 +====================++======+ Cash flows         ||      +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-+ assets:bank:saving ||   $1 + assets:cash        ||  $\-2 +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-+                    ||  $\-1 +.EE+.PP+This command is a higher\-level variant of the \f[CR]balance\f[R]+command, and supports many of that command\[aq]s features, such as+multi\-period reports.+It is similar to+\f[CR]hledger balance assets not:fixed not:investment not:receivable\f[R],+but with smarter account detection.+.PP+This command also supports the output destination and output format+options The output formats supported are \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]html\f[R], and+\f[CR]json\f[R].+.SS incomestatement+(is)+.PP+Show revenue inflows and expense outflows during the report period.+Amounts are shown with normal positive sign, as in conventional+financial statements.+.PP+This command displays an income statement, showing revenues and expenses+during one or more periods.+.PP+It shows accounts declared with the \f[CR]Revenue\f[R] or+\f[CR]Expense\f[R] type (see account types).+Or if no such accounts are declared, it shows top\-level accounts named+\f[CR]revenue\f[R] or \f[CR]income\f[R] or \f[CR]expense\f[R] (case+insensitive, plurals allowed) and their subaccounts.+.PP+Example:+.IP+.EX+$ hledger incomestatement+Income Statement 2008++                   || 2008 +===================++======+ Revenues          ||      +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-+ income:gifts      ||   $1 + income:salary     ||   $1 +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-+                   ||   $2 +===================++======+ Expenses          ||      +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-+ expenses:food     ||   $1 + expenses:supplies ||   $1 +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-+                   ||   $2 +===================++======+ Net:              ||    0 +.EE+.PP+This command is a higher\-level variant of the \f[CR]balance\f[R]+command, and supports many of that command\[aq]s features, such as+multi\-period reports.+It is similar to+\f[CR]hledger balance \[aq](revenues|income)\[aq] expenses\f[R], but+with smarter account detection, and revenues/income displayed with their+sign flipped.+.PP+This command also supports the output destination and output format+options The output formats supported are \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]html\f[R], and+\f[CR]json\f[R].+.SH Advanced report commands+.SS balance+(bal)+.PP+A flexible, general purpose \[dq]summing\[dq] 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.+.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+changes and more, during one time period or many.+Generally it shows a table, with rows representing accounts, and columns+representing periods.+.PP+Note there are some higher\-level variants of the \f[CR]balance\f[R]+command with convenient defaults, which can be simpler to use:+\f[CR]balancesheet\f[R], \f[CR]balancesheetequity\f[R],+\f[CR]cashflow\f[R] and \f[CR]incomestatement\f[R].+When you need more control, then use \f[CR]balance\f[R].+.SS balance features+Here\[aq]s a quick overview of the \f[CR]balance\f[R] command\[aq]s+features, followed by more detailed descriptions and examples.+Many of these work with the higher\-level commands as well.+.PP+\f[CR]balance\f[R] can show..+.IP \[bu] 2+accounts as a list (\f[CR]\-l\f[R]) or a tree (\f[CR]\-t\f[R])+.IP \[bu] 2+optionally depth\-limited (\f[CR]\-[1\-9]\f[R])+.IP \[bu] 2+sorted by declaration order and name, or by amount+.PP+\&..and their..+.IP \[bu] 2+balance changes (the default)+.IP \[bu] 2+or actual and planned balance changes (\f[CR]\-\-budget\f[R])+.IP \[bu] 2+or value of balance changes (\f[CR]\-V\f[R])+.IP \[bu] 2+or change of balance values (\f[CR]\-\-valuechange\f[R])+.IP \[bu] 2+or unrealised capital gain/loss (\f[CR]\-\-gain\f[R])+.IP \[bu] 2+or balance changes from sibling postings+(\f[CR]\-\-related\f[R]/\f[CR]\-r\f[R])+.IP \[bu] 2+or postings count (\f[CR]\-\-count\f[R])+.PP+\&..in..+.IP \[bu] 2+one time period (the whole journal period by default)+.IP \[bu] 2+or multiple periods (\f[CR]\-D\f[R], \f[CR]\-W\f[R], \f[CR]\-M\f[R],+\f[CR]\-Q\f[R], \f[CR]\-Y\f[R], \f[CR]\-p INTERVAL\f[R])+.PP+\&..either..+.IP \[bu] 2+per period (the default)+.IP \[bu] 2+or accumulated since report start date (\f[CR]\-\-cumulative\f[R])+.IP \[bu] 2+or accumulated since account creation (\f[CR]\-\-historical/\-H\f[R])+.PP+\&..possibly converted to..+.IP \[bu] 2+cost+(\f[CR]\-\-value=cost[,COMM]\f[R]/\f[CR]\-\-cost\f[R]/\f[CR]\-B\f[R])+.IP \[bu] 2+or market value, as of transaction dates+(\f[CR]\-\-value=then[,COMM]\f[R])+.IP \[bu] 2+or at period ends (\f[CR]\-\-value=end[,COMM]\f[R])+.IP \[bu] 2+or now (\f[CR]\-\-value=now\f[R])+.IP \[bu] 2+or at some other date (\f[CR]\-\-value=YYYY\-MM\-DD\f[R])+.PP+\&..with..+.IP \[bu] 2+totals (\f[CR]\-T\f[R]), averages (\f[CR]\-A\f[R]), percentages+(\f[CR]\-%\f[R]), inverted sign (\f[CR]\-\-invert\f[R])+.IP \[bu] 2+rows and columns swapped (\f[CR]\-\-transpose\f[R])+.IP \[bu] 2+another field used as account name (\f[CR]\-\-pivot\f[R])+.IP \[bu] 2+custom\-formatted line items (single\-period reports only)+(\f[CR]\-\-format\f[R])+.IP \[bu] 2+commodities displayed on the same line or multiple lines+(\f[CR]\-\-layout\f[R])+.PP+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].+In \f[CR]txt\f[R] output in a colour\-supporting terminal, negative+amounts are shown in red.+.SS Simple balance report+With no arguments, \f[CR]balance\f[R] 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.+(\[dq]Simple\[dq] here means just one column of numbers, covering a+single period.+You can also have multi\-period reports, described later.)+.PP+For real\-world accounts, these numbers will normally be their end+balance at the end of the journal period; more on this below.+.PP+Accounts are sorted by declaration order if any, and then alphabetically+by account name.+For instance (using examples/sample.journal):+.IP+.EX+$ 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  +.EE+.PP+Accounts with a zero balance (and no non\-zero subaccounts, in tree mode+\- see below) are hidden by default.+Use \f[CR]\-E/\-\-empty\f[R] to show them (revealing+\f[CR]assets:bank:checking\f[R] here):+.IP+.EX+$ 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  +.EE+.PP+The total of the amounts displayed is shown as the last line, unless+\f[CR]\-N\f[R]/\f[CR]\-\-no\-total\f[R] is used.+.SS Balance report line format+For single\-period balance reports displayed in the terminal (only), you+can use \f[CR]\-\-format FMT\f[R] to customise the format and content of+each line.+Eg:+.IP+.EX+$ hledger \-f examples/sample.journal balance \-\-format \[dq]%20(account) %12(total)\[dq]+              assets          $\-1+         bank:saving           $1+                cash          $\-2+            expenses           $2+                food           $1+            supplies           $1+              income          $\-2+               gifts          $\-1+              salary          $\-1+   liabilities:debts           $1+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+                                0+.EE+.PP+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:+.PP+\f[CR]%[MIN][.MAX](FIELDNAME)\f[R]+.IP \[bu] 2+MIN pads with spaces to at least this width (optional)+.IP \[bu] 2+MAX truncates at this width (optional)+.IP \[bu] 2+FIELDNAME must be enclosed in parentheses, and can be one of:+.RS 2+.IP \[bu] 2+\f[CR]depth_spacer\f[R] \- a number of spaces equal to the account\[aq]s+depth, or if MIN is specified, MIN * depth spaces.+.IP \[bu] 2+\f[CR]account\f[R] \- the account\[aq]s name+.IP \[bu] 2+\f[CR]total\f[R] \- the account\[aq]s balance/posted total, right+justified+.RE+.PP+Also, FMT can begin with an optional prefix to control how+multi\-commodity amounts are rendered:+.IP \[bu] 2+\f[CR]%_\f[R] \- render on multiple lines, bottom\-aligned (the default)+.IP \[bu] 2+\f[CR]%\[ha]\f[R] \- render on multiple lines, top\-aligned+.IP \[bu] 2+\f[CR]%,\f[R] \- render on one line, comma\-separated+.PP+There are some quirks.+Eg in one\-line mode, \f[CR]%(depth_spacer)\f[R] has no effect, instead+\f[CR]%(account)\f[R] has indentation built in.+\ Experimentation may be needed to get pleasing results.+.PP+Some example formats:+.IP \[bu] 2+\f[CR]%(total)\f[R] \- the account\[aq]s total+.IP \[bu] 2+\f[CR]%\-20.20(account)\f[R] \- the account\[aq]s name, left justified,+padded to 20 characters and clipped at 20 characters+.IP \[bu] 2+\f[CR]%,%\-50(account)  %25(total)\f[R] \- account name padded to 50+characters, total padded to 20 characters, with multiple commodities+rendered on one line+.IP \[bu] 2+\f[CR]%20(total)  %2(depth_spacer)%\-(account)\f[R] \- the default+format for the single\-column balance report+.SS 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:+.IP+.EX+$ hledger \-f examples/sample.journal bal \-\-cleared assets date:200806+                 $\-2  assets:cash+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+                 $\-2  +.EE+.SS List or tree mode+By default, or with \f[CR]\-l/\-\-flat\f[R], accounts are shown as a+flat list with their full names visible, as in the examples above.+.PP+With \f[CR]\-t/\-\-tree\f[R], the account hierarchy is shown, with+subaccounts\[aq] \[dq]leaf\[dq] names indented below their parent:+.IP+.EX+$ 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+.EE+.PP+Notes:+.IP \[bu] 2+\[dq]Boring\[dq] accounts are combined with their subaccount for more+compact output, unless \f[CR]\-\-no\-elide\f[R] is used.+Boring accounts have no balance of their own and just one subaccount (eg+\f[CR]assets:bank\f[R] and \f[CR]liabilities\f[R] above).+.IP \[bu] 2+All balances shown are \[dq]inclusive\[dq], 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\[aq]s final total is the sum of the top\-level+balances shown, not of all the balances shown.+.IP \[bu] 2+Each group of sibling accounts (ie, under a common parent) is sorted+separately.+.SS Depth limiting+With a \f[CR]depth:NUM\f[R] query, or \f[CR]\-\-depth NUM\f[R] option,+or just \f[CR]\-NUM\f[R] (eg: \f[CR]\-3\f[R]) 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.+.PP+Account balances at the depth limit always include the balances from any+deeper subaccounts (even in list mode).+Eg, limiting to depth 1:+.IP+.EX+$ hledger \-f examples/sample.journal balance \-1+                 $\-1  assets+                  $2  expenses+                 $\-2  income+                  $1  liabilities+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+                   0  +.EE+.SS Dropping top\-level accounts+You can also hide one or more top\-level account name parts, using+\f[CR]\-\-drop NUM\f[R].+This can be useful for hiding repetitive top\-level account names:+.IP+.EX+$ hledger \-f examples/sample.journal bal expenses \-\-drop 1+                  $1  food+                  $1  supplies+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+                  $2  +.EE+.PP+.SS Showing declared accounts+With \f[CR]\-\-declared\f[R], 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+\f[CR]\-E/\-\-empty\f[R] to see them.)+.PP+More precisely, \f[I]leaf\f[R] declared accounts (with no subaccounts)+will be included, since those are usually the more useful in reports.+.PP+The idea of this is to be able to see a useful \[dq]complete\[dq]+balance report, even when you don\[aq]t have transactions in all of your+declared accounts yet.+.SS Sorting by amount+With \f[CR]\-S/\-\-sort\-amount\f[R], accounts with the largest (most+positive) balances are shown first.+Eg: \f[CR]hledger bal expenses \-MAS\f[R] 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).+.PP+Revenues and liability balances are typically negative, however, so+\f[CR]\-S\f[R] shows these in reverse order.+To work around this, you can add \f[CR]\-\-invert\f[R] to flip the+signs.+(Or, use one of the higher\-level reports, which flip the sign+automatically.+Eg: \f[CR]hledger incomestatement \-MAS\f[R]).+.PP+.SS Percentages+With \f[CR]\-%/\-\-percent\f[R], balance reports show each account\[aq]s+value expressed as a percentage of the (column) total.+.PP+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:+.IP+.EX+$ hledger bal \-% amt:\[ga]>0\[ga]+$ hledger bal \-% amt:\[ga]<0\[ga]+.EE+.PP+Similarly, if the amounts in a column have mixed commodities, convert+them to one commodity with \f[CR]\-B\f[R], \f[CR]\-V\f[R],+\f[CR]\-X\f[R] or \f[CR]\-\-value\f[R], or make a separate report for+each commodity:+.IP+.EX+$ hledger bal \-% cur:\[rs]\[rs]$+$ hledger bal \-% cur:€+.EE+.SS Multi\-period balance report+With a report interval (set by the \f[CR]\-D/\-\-daily\f[R],+\f[CR]\-W/\-\-weekly\f[R], \f[CR]\-M/\-\-monthly\f[R],+\f[CR]\-Q/\-\-quarterly\f[R], \f[CR]\-Y/\-\-yearly\f[R], or+\f[CR]\-p/\-\-period\f[R] flag), \f[CR]balance\f[R] shows a tabular+report, with columns representing successive time periods (and a title):+.IP+.EX+$ 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 +.EE+.PP+Notes:+.IP \[bu] 2+The report\[aq]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).+.IP \[bu] 2+Leading and trailing periods (columns) containing all zeroes are not+shown, unless \f[CR]\-E/\-\-empty\f[R] is used.+.IP \[bu] 2+Accounts (rows) containing all zeroes are not shown, unless+\f[CR]\-E/\-\-empty\f[R] is used.+.IP \[bu] 2+Amounts with many commodities are shown in abbreviated form, unless+\f[CR]\-\-no\-elide\f[R] is used.+.IP \[bu] 2+Average and/or total columns can be added with the+\f[CR]\-A/\-\-average\f[R] and \f[CR]\-T/\-\-row\-total\f[R] flags.+.IP \[bu] 2+The \f[CR]\-\-transpose\f[R] flag can be used to exchange rows and+columns.+.IP \[bu] 2+The \f[CR]\-\-pivot FIELD\f[R] option causes a different transaction+field to be used as \[dq]account name\[dq].+See PIVOTING.+.IP \[bu] 2+The \f[CR]\-\-summary\-only\f[R] flag (\f[CR]\-\-summary\f[R] also+works) hides all but the Total and Average columns (those should be+enabled with \f[CR]\-\-row\-total\f[R] and \f[CR]\-A/\-\-average\f[R]).+.PP+Multi\-period reports with many periods can be too wide for easy viewing+in the terminal.+Here are some ways to handle that:+.IP \[bu] 2+Hide the totals row with \f[CR]\-N/\-\-no\-total\f[R]+.IP \[bu] 2+Filter to a single currency with \f[CR]cur:\f[R]+.IP \[bu] 2+Convert to a single currency with+\f[CR]\-V [\-\-infer\-market\-price]\f[R]+.IP \[bu] 2+Use a more compact layout like \f[CR]\-\-layout=bare\f[R]+.IP \[bu] 2+Maximize the terminal window+.IP \[bu] 2+Reduce the terminal\[aq]s font size+.IP \[bu] 2+View with a pager like less, eg:+\f[CR]hledger bal \-D \-\-color=yes | less \-RS\f[R]+.IP \[bu] 2+Output as CSV and use a CSV viewer like visidata+(\f[CR]hledger bal \-D \-O csv | vd \-f csv\f[R]), Emacs\[aq] csv\-mode+(\f[CR]M\-x csv\-mode, C\-c C\-a\f[R]), or a spreadsheet+(\f[CR]hledger bal \-D \-o a.csv && open a.csv\f[R])+.IP \[bu] 2+Output as HTML and view with a browser:+\f[CR]hledger bal \-D \-o a.html && open a.html\f[R]+.SS Balance change, end balance+It\[aq]s important to be clear on the meaning of the numbers shown in+balance reports.+Here is some terminology we use:+.PP+A \f[B]\f[BI]balance change\f[B]\f[R] is the net amount added to, or+removed from, an account during some period.+.PP+An \f[B]\f[BI]end balance\f[B]\f[R] is the amount accumulated in an+account as of some date (and some time, but hledger doesn\[aq]t store+that; assume end of day in your timezone).+It is the sum of previous balance changes.+.PP+We call it a \f[B]\f[BI]historical end balance\f[B]\f[R] if it includes+all balance changes since the account was created.+For a real world account, this means it will match the \[dq]historical+record\[dq], eg the balances reported in your bank statements or bank+web UI.+(If they are correct!)+.PP+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.+.PP+\f[CR]balance\f[R] shows balance changes by default.+To see accurate historical end balances:+.IP "1." 3+Initialise account starting balances with an \[dq]opening balances\[dq]+transaction (a transfer from equity to the account), unless the journal+covers the account\[aq]s full lifetime.+.IP "2." 3+Include all of of the account\[aq]s prior postings in the report, by not+specifying a report start date, or by using the+\f[CR]\-H/\-\-historical\f[R] flag.+(\f[CR]\-H\f[R] causes report start date to be ignored when summing+postings.)+.SS 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\[aq]t worry \- this is for+advanced reporting, and it does take time and experimentation to get+familiar with all the report modes.+.PP+There are three important option groups:+.PP+\f[CR]hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] ...\f[R]+.SS Calculation type+The basic calculation to perform for each table cell.+It is one of:+.IP \[bu] 2+\f[CR]\-\-sum\f[R] : sum the posting amounts (\f[B]default\f[R])+.IP \[bu] 2+\f[CR]\-\-budget\f[R] : sum the amounts, but also show the budget goal+amount (for each account/period)+.IP \[bu] 2+\f[CR]\-\-valuechange\f[R] : show the change in period\-end historical+balance values (caused by deposits, withdrawals, and/or market price+fluctuations)+.IP \[bu] 2+\f[CR]\-\-gain\f[R] : show the unrealised capital gain/loss, (the+current valued balance minus each amount\[aq]s original cost)+.IP \[bu] 2+\f[CR]\-\-count\f[R] : show the count of postings+.SS Accumulation type+How amounts should accumulate across a report\[aq]s subperiods/columns.+Another way to say it: which time period\[aq]s postings should+contribute to each cell\[aq]s calculation.+It is one of:+.IP \[bu] 2+\f[CR]\-\-change\f[R] : calculate with postings from column start to+column end, ie \[dq]just this column\[dq].+Typically used to see revenues/expenses.+(\f[B]default for balance, cashflow, incomestatement\f[R])+.IP \[bu] 2+\f[CR]\-\-cumulative\f[R] : calculate with postings from report start to+column end, ie \[dq]previous columns plus this column\[dq].+Typically used to show changes accumulated since the report\[aq]s start+date.+Not often used.+.IP \[bu] 2+\f[CR]\-\-historical/\-H\f[R] : calculate with postings from journal+start to column end, ie \[dq]all postings from before report start date+until this column\[aq]s end\[dq].+Typically used to see historical end balances of+assets/liabilities/equity.+(\f[B]default for balancesheet, balancesheetequity\f[R])+.SS Valuation type+Which kind of value or cost conversion should be applied, if any, before+displaying the report.+It is one of:+.IP \[bu] 2+no valuation type : don\[aq]t convert to cost or value+(\f[B]default\f[R])+.IP \[bu] 2+\f[CR]\-\-value=cost[,COMM]\f[R] : convert amounts to cost (then+optionally to some other commodity)+.IP \[bu] 2+\f[CR]\-\-value=then[,COMM]\f[R] : convert amounts to market value on+transaction dates+.IP \[bu] 2+\f[CR]\-\-value=end[,COMM]\f[R] : convert amounts to market value on+period end date(s)+.PD 0+.P+.PD+(\f[B]default with \f[CB]\-\-valuechange\f[B], \f[CB]\-\-gain\f[B]\f[R])+.IP \[bu] 2+\f[CR]\-\-value=now[,COMM]\f[R] : convert amounts to market value on+today\[aq]s date+.IP \[bu] 2+\f[CR]\-\-value=YYYY\-MM\-DD[,COMM]\f[R] : convert amounts to market+value on another date+.PP+or one of the equivalent simpler flags:+.IP \[bu] 2+\f[CR]\-B/\-\-cost\f[R] : like \-\-value=cost (though, note \-\-cost and+\-\-value are independent options which can both be used at once)+.IP \[bu] 2+\f[CR]\-V/\-\-market\f[R] : like \-\-value=end+.IP \[bu] 2+\f[CR]\-X COMM/\-\-exchange COMM\f[R] : like \-\-value=end,COMM+.PP+See Cost reporting and Value reporting for more about these.+.SS 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:+.IP \[bu] 2+\f[CR]\-\-valuechange\f[R] implies \f[CR]\-\-value=end\f[R]+.IP \[bu] 2+\f[CR]\-\-valuechange\f[R] makes \f[CR]\-\-change\f[R] the default when+used with the \f[CR]balancesheet\f[R]/\f[CR]balancesheetequity\f[R]+commands+.IP \[bu] 2+\f[CR]\-\-cumulative\f[R] or \f[CR]\-\-historical\f[R] disables+\f[CR]\-\-row\-total/\-T\f[R]+.PP+For reference, here is what the combinations of accumulation and+valuation show:+.PP+.TS+tab(@);+lw(7.9n) lw(16.4n) lw(16.9n) lw(15.1n) lw(13.7n).+T{+Valuation:> Accumulation:v+T}@T{+no valuation+T}@T{+\f[CR]\-\-value= then\f[R]+T}@T{+\f[CR]\-\-value= end\f[R]+T}@T{+\f[CR]\-\-value= YYYY\-MM\-DD /now\f[R]+T}+_+T{+\f[CR]\-\-change\f[R]+T}@T{+change in period+T}@T{+sum of posting\-date market values in period+T}@T{+period\-end value of change in period+T}@T{+DATE\-value of change in period+T}+T{+\f[CR]\-\-cumulative\f[R]+T}@T{+change from report start to period end+T}@T{+sum of posting\-date market values from report start to period end+T}@T{+period\-end value of change from report start to period end+T}@T{+DATE\-value of change from report start to period end+T}+T{+\f[CR]\-\-historical /\-H\f[R]+T}@T{+change from journal start to period end (historical end balance)+T}@T{+sum of posting\-date market values from journal start to period end+T}@T{+period\-end value of change from journal start to period end+T}@T{+DATE\-value of change from journal start to period end+T}+.TE+.SS Budget report+The \f[CR]\-\-budget\f[R] report type is like a regular balance report,+but with two main differences:+.IP \[bu] 2+Budget goals and performance percentages are also shown, in brackets+.IP \[bu] 2+Accounts which don\[aq]t have budget goals are hidden by default.+.PP+This is useful for comparing planned and actual income, expenses, time+usage, etc.+.PP+Periodic transaction rules are used to define budget goals.+For example, here\[aq]s a periodic rule defining monthly goals for bus+travel and food expenses:+.IP+.EX+;; Budget+\[ti] monthly+  (expenses:bus)              $30+  (expenses:food)            $400+.EE+.PP+After recording some actual expenses,+.IP+.EX+;; 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+.EE+.PP+we can see a budget report like this:+.IP+.EX+$ 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] +.EE+.PP+This is \[dq]goal\-based budgeting\[dq]; you define goals for accounts+and periods, often recurring, and hledger shows performance relative to+the goals.+This contrasts with \[dq]envelope budgeting\[dq], 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.+.SS Using the budget report+Historically this report has been confusing and fragile.+hledger\[aq]s version should be relatively robust and intuitive, but you+may still find surprises.+Here are more notes to help with learning and troubleshooting.+.IP \[bu] 2+In the above example, \f[CR]expenses:bus\f[R] and+\f[CR]expenses:food\f[R] are shown because they have budget goals during+the report period.+.IP \[bu] 2+Their parent \f[CR]expenses\f[R] is also shown, with budget goals+aggregated from the children.+.IP \[bu] 2+The subaccounts \f[CR]expenses:food:groceries\f[R] and+\f[CR]expenses:food:dining\f[R] are not shown since they have no budget+goal of their own, but they contribute to \f[CR]expenses:food\f[R]\[aq]s+actual amount.+.IP \[bu] 2+Unbudgeted accounts \f[CR]expenses:movies\f[R] and+\f[CR]expenses:gifts\f[R] are also not shown, but they contribute to+\f[CR]expenses\f[R]\[aq]s actual amount.+.IP \[bu] 2+The other unbudgeted accounts \f[CR]income\f[R] and+\f[CR]assets:bank:checking\f[R] are grouped as \f[CR]<unbudgeted>\f[R].+.IP \[bu] 2+\f[CR]\-\-depth\f[R] or \f[CR]depth:\f[R] can be used to limit report+depth in the usual way (but will not reveal unbudgeted subaccounts).+.IP \[bu] 2+Amounts are always inclusive of subaccounts (even in+\f[CR]\-l/\-\-list\f[R] mode).+.IP \[bu] 2+Numbers displayed in a \-\-budget report will not always agree with the+totals, because of hidden unbudgeted accounts; this is normal.+\f[CR]\-E/\-\-empty\f[R] can be used to reveal the hidden accounts.+.IP \[bu] 2+In the periodic rules used for setting budget goals, unbalanced postings+are convenient.+.IP \[bu] 2+You can filter budget reports with the usual queries, eg to focus on+particular accounts.+It\[aq]s common to restrict them to just expenses.+(The \f[CR]<unbudgeted>\f[R] account is occasionally hard to exclude;+this is because of date surprises, discussed below.)+.IP \[bu] 2+When you have multiple currencies, you may want to convert them to one+(\f[CR]\-X COMM \-\-infer\-market\-prices\f[R]) and/or show just one at+a time (\f[CR]cur:COMM\f[R]).+If you do need to show multiple currencies at once,+\f[CR]\-\-layout bare\f[R] can be helpful.+.IP \[bu] 2+You can \[dq]roll over\[dq] amounts (actual and budgeted) to the next+period with \f[CR]\-\-cumulative\f[R].+.PP+See also: https://hledger.org/budgeting.html.+.SS 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 \f[CR]expenses:food\f[R] budget.+(Also the \f[CR]<unbudgeted>\f[R] account should be excluded by the+\f[CR]expenses\f[R] query, but isn\[aq]t.):+.IP+.EX+\[ti] monthly in 2020+  (expenses:food)  $500++2020\-01\-15+  expenses:food    $400+  assets:checking+.EE+.IP+.EX+$ 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] +.EE+.PP+In this case, the budget goal transactions are generated on first days+of of month (this can be seen with+\f[CR]hledger print \-\-forecast tag:generated expenses\f[R]).+Whereas the report period defaults to just the 15th day of january (this+can be seen from the report table\[aq]s column headings).+.PP+To fix this kind of thing, be more explicit about the report period+(and/or the periodic rules\[aq] dates).+In this case, adding \f[CR]\-b 2020\f[R] does the trick.+.SS 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.+.PP+You can select a subset of periodic rules by providing an argument to+the \f[CR]\-\-budget\f[R] flag.+\f[CR]\-\-budget=DESCPAT\f[R] 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.+.SS Budgeting vs forecasting+\f[CR]\-\-forecast\f[R] and \f[CR]\-\-budget\f[R] 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:+.PP+.TS+tab(@);+lw(38.2n) lw(31.8n).+T{+\-\-forecast+T}@T{+\-\-budget+T}+_+T{+is a general option; it enables forecasting with all reports+T}@T{+is a balance command option; it selects the balance report\[aq]s budget+mode+T}+T{+generates visible transactions which appear in reports+T}@T{+generates invisible transactions which produce goal amounts+T}+T{+generates forecast transactions from after the last regular transaction,+to the end of the report period; or with an argument+\f[CR]\-\-forecast=PERIODEXPR\f[R] generates them throughout the+specified period, both optionally restricted by periods specified in the+periodic transaction rules+T}@T{+generates budget goal transactions throughout the report period,+optionally restricted by periods specified in the periodic transaction+rules+T}+T{+uses all periodic rules+T}@T{+uses all periodic rules; or with an argument+\f[CR]\-\-budget=DESCPAT\f[R] uses just the rules matched by DESCPAT+T}+.TE+.SS Balance report layout+The \f[CR]\-\-layout\f[R] 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:+.IP \[bu] 2+\f[CR]\-\-layout=wide[,WIDTH]\f[R]: commodities are shown on a single+line, optionally elided to WIDTH+.IP \[bu] 2+\f[CR]\-\-layout=tall\f[R]: each commodity is shown on a separate line+.IP \[bu] 2+\f[CR]\-\-layout=bare\f[R]: commodity symbols are in their own column,+amounts are bare numbers+.IP \[bu] 2+\f[CR]\-\-layout=tidy\f[R]: data is normalised to easily\-consumed+\[dq]tidy\[dq] form, with one row per data value+.PP+Here are the \f[CR]\-\-layout\f[R] modes supported by each output format+Only CSV output supports all of them:+.PP+.TS+tab(@);+l l l l l l.+T{+\-+T}@T{+txt+T}@T{+csv+T}@T{+html+T}@T{+json+T}@T{+sql+T}+_+T{+wide+T}@T{+Y+T}@T{+Y+T}@T{+Y+T}@T{+T}@T{+T}+T{+tall+T}@T{+Y+T}@T{+Y+T}@T{+Y+T}@T{+T}@T{+T}+T{+bare+T}@T{+Y+T}@T{+Y+T}@T{+Y+T}@T{+T}@T{+T}+T{+tidy+T}@T{+T}@T{+Y+T}@T{+T}@T{+T}@T{+T}+.TE+.PP+Examples:+.SS Wide layout+With many commodities, reports can be very wide:+.IP+.EX+$ 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 +.EE+.PP+A width limit reduces the width, but some commodities will be hidden:+.IP+.EX+$ 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.. +.EE+.SS Tall layout+Each commodity gets a new line (may be different in each column), and+account names are repeated:+.IP+.EX+$ 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 +.EE+.SS Bare layout+Commodity symbols are kept in one column, each commodity has its own+row, amounts are bare numbers, account names are repeated:+.IP+.EX+$ 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 +.EE+.PP+Bare layout also affects CSV output, which is useful for producing data+that is easier to consume, eg for making charts:+.IP+.EX+$ hledger \-f examples/bcexample.hledger bal assets:us:etrade \-3 \-O csv \-\-layout=bare+\[dq]account\[dq],\[dq]commodity\[dq],\[dq]balance\[dq]+\[dq]Assets:US:ETrade\[dq],\[dq]GLD\[dq],\[dq]70.00\[dq]+\[dq]Assets:US:ETrade\[dq],\[dq]ITOT\[dq],\[dq]17.00\[dq]+\[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]+.EE+.PP+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 \f[CR]hledger\-bar\f[R] confusingly (workaround: add a+\f[CR]cur:\f[R] query to exclude the no\-symbol row).+.SS Tidy layout+This produces normalised \[dq]tidy data\[dq] (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:+.IP+.EX+$ hledger \-f examples/bcexample.hledger bal assets:us:etrade \-3 \-Y \-O csv \-\-layout=tidy+\[dq]account\[dq],\[dq]period\[dq],\[dq]start_date\[dq],\[dq]end_date\[dq],\[dq]commodity\[dq],\[dq]value\[dq]+\[dq]Assets:US:ETrade\[dq],\[dq]2012\[dq],\[dq]2012\-01\-01\[dq],\[dq]2012\-12\-31\[dq],\[dq]GLD\[dq],\[dq]0\[dq]+\[dq]Assets:US:ETrade\[dq],\[dq]2012\[dq],\[dq]2012\-01\-01\[dq],\[dq]2012\-12\-31\[dq],\[dq]ITOT\[dq],\[dq]10.00\[dq]+\[dq]Assets:US:ETrade\[dq],\[dq]2012\[dq],\[dq]2012\-01\-01\[dq],\[dq]2012\-12\-31\[dq],\[dq]USD\[dq],\[dq]337.18\[dq]+\[dq]Assets:US:ETrade\[dq],\[dq]2012\[dq],\[dq]2012\-01\-01\[dq],\[dq]2012\-12\-31\[dq],\[dq]VEA\[dq],\[dq]12.00\[dq]+\[dq]Assets:US:ETrade\[dq],\[dq]2012\[dq],\[dq]2012\-01\-01\[dq],\[dq]2012\-12\-31\[dq],\[dq]VHT\[dq],\[dq]106.00\[dq]+\[dq]Assets:US:ETrade\[dq],\[dq]2013\[dq],\[dq]2013\-01\-01\[dq],\[dq]2013\-12\-31\[dq],\[dq]GLD\[dq],\[dq]70.00\[dq]+\[dq]Assets:US:ETrade\[dq],\[dq]2013\[dq],\[dq]2013\-01\-01\[dq],\[dq]2013\-12\-31\[dq],\[dq]ITOT\[dq],\[dq]18.00\[dq]+\[dq]Assets:US:ETrade\[dq],\[dq]2013\[dq],\[dq]2013\-01\-01\[dq],\[dq]2013\-12\-31\[dq],\[dq]USD\[dq],\[dq]\-98.12\[dq]+\[dq]Assets:US:ETrade\[dq],\[dq]2013\[dq],\[dq]2013\-01\-01\[dq],\[dq]2013\-12\-31\[dq],\[dq]VEA\[dq],\[dq]10.00\[dq]+\[dq]Assets:US:ETrade\[dq],\[dq]2013\[dq],\[dq]2013\-01\-01\[dq],\[dq]2013\-12\-31\[dq],\[dq]VHT\[dq],\[dq]18.00\[dq]+\[dq]Assets:US:ETrade\[dq],\[dq]2014\[dq],\[dq]2014\-01\-01\[dq],\[dq]2014\-12\-31\[dq],\[dq]GLD\[dq],\[dq]0\[dq]+\[dq]Assets:US:ETrade\[dq],\[dq]2014\[dq],\[dq]2014\-01\-01\[dq],\[dq]2014\-12\-31\[dq],\[dq]ITOT\[dq],\[dq]\-11.00\[dq]+\[dq]Assets:US:ETrade\[dq],\[dq]2014\[dq],\[dq]2014\-01\-01\[dq],\[dq]2014\-12\-31\[dq],\[dq]USD\[dq],\[dq]4881.44\[dq]+\[dq]Assets:US:ETrade\[dq],\[dq]2014\[dq],\[dq]2014\-01\-01\[dq],\[dq]2014\-12\-31\[dq],\[dq]VEA\[dq],\[dq]14.00\[dq]+\[dq]Assets:US:ETrade\[dq],\[dq]2014\[dq],\[dq]2014\-01\-01\[dq],\[dq]2014\-12\-31\[dq],\[dq]VHT\[dq],\[dq]170.00\[dq]+.EE+.SS Some useful balance reports+Some frequently used \f[CR]balance\f[R] options/reports are:+.IP \[bu] 2+\f[CR]bal \-M revenues expenses\f[R]+.PD 0+.P+.PD+Show revenues/expenses in each month.+Also available as the \f[CR]incomestatement\f[R] command.+.IP \[bu] 2+\f[CR]bal \-M \-H assets liabilities\f[R]+.PD 0+.P+.PD+Show historical asset/liability balances at each month end.+Also available as the \f[CR]balancesheet\f[R] command.+.IP \[bu] 2+\f[CR]bal \-M \-H assets liabilities equity\f[R]+.PD 0+.P+.PD+Show historical asset/liability/equity balances at each month end.+Also available as the \f[CR]balancesheetequity\f[R] command.+.IP \[bu] 2+\f[CR]bal \-M assets not:receivable\f[R]+.PD 0+.P+.PD+Show changes to liquid assets in each month.+Also available as the \f[CR]cashflow\f[R] command.+.PP+Also:+.IP \[bu] 2+\f[CR]bal \-M expenses \-2 \-SA\f[R]+.PD 0+.P+.PD+Show monthly expenses summarised to depth 2 and sorted by average+amount.+.IP \[bu] 2+\f[CR]bal \-M \-\-budget expenses\f[R]+.PD 0+.P+.PD+Show monthly expenses and budget goals.+.IP \[bu] 2+\f[CR]bal \-M \-\-valuechange investments\f[R]+.PD 0+.P+.PD+Show monthly change in market value of investment assets.+.IP \[bu] 2+\f[CR]bal investments \-\-valuechange \-D date:lastweek amt:\[aq]>1000\[aq] \-STA [\-\-invert]\f[R]+.PD 0+.P+.PD+Show top gainers [or losers] last week+.SS roi+Shows the time\-weighted (TWR) and money\-weighted (IRR) rate of return+on your investments.+.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+query to identify your profit and loss transactions with+\f[CR]\-\-pnl\f[R].+.PP+If you do not record changes in the value of your investment manually,+or do not require computation of time\-weighted return (TWR),+\f[CR]\-\-pnl\f[R] could be an empty query+(\f[CR]\-\-pnl \[dq]\[dq]\f[R] or \f[CR]\-\-pnl STR\f[R] where+\f[CR]STR\f[R] does not match any of your accounts).+.PP+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.+.PP+Price directives will be taken into account if you supply appropriate+\f[CR]\-\-cost\f[R] or \f[CR]\-\-value\f[R] flags (see VALUATION).+.PP+Note, in some cases this report can fail, for these reasons:+.IP \[bu] 2+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.+.IP \[bu] 2+Error (SearchFailed): Failed to find solution for Internal Rate of+Return (IRR).+Either search does not converge to a solution, or converges too slowly.+.PP+Examples:+.IP \[bu] 2+Using roi to compute total return of investment in stocks:+https://github.com/simonmichael/hledger/blob/master/examples/investing/roi\-unrealised.ledger+.IP \[bu] 2+Cookbook > Return on Investment: https://hledger.org/roi.html+.SS Spaces and special characters in \f[CR]\-\-inv\f[R] and \f[CR]\-\-pnl\f[R]+Note that \f[CR]\-\-inv\f[R] and \f[CR]\-\-pnl\f[R]\[aq]s argument is a+query, and queries could have several space\-separated terms (see+QUERIES).+.PP+To indicate that all search terms form single command\-line argument,+you will need to put them in quotes (see Special characters):+.IP+.EX+$ hledger roi \-\-inv \[aq]term1 term2 term3 ...\[aq]+.EE+.PP+If any query terms contain spaces themselves, you will need an extra+level of nested quoting, eg:+.IP+.EX+$ hledger roi \-\-inv=\[dq]\[aq]Assets:Test 1\[aq]\[dq] \-\-pnl=\[dq]\[aq]Equity:Unrealized Profit and Loss\[aq]\[dq]+.EE+.SS Semantics of \f[CR]\-\-inv\f[R] and \f[CR]\-\-pnl\f[R]+Query supplied to \f[CR]\-\-inv\f[R] has to match all transactions that+are related to your investment.+Transactions not matching \f[CR]\-\-inv\f[R] will be ignored.+.PP+In these transactions, ROI will conside postings that match+\f[CR]\-\-inv\f[R] to be \[dq]investment postings\[dq] and other+postings (not matching \f[CR]\-\-inv\f[R]) will be sorted into two+categories: \[dq]cash flow\[dq] and \[dq]profit and loss\[dq], as ROI+needs to know which part of the investment value is your contributions+and which is due to the return on investment.+.IP \[bu] 2+\[dq]Cash flow\[dq] is depositing or withdrawing money, buying or+selling assets, or otherwise converting between your investment+commodity and any other commodity.+Example:+.RS 2+.IP+.EX+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+.EE+.RE+.IP \[bu] 2+\[dq]Profit and loss\[dq] is change in the value of your investment:+.RS 2+.IP+.EX+2019\-06\-01 Snake Oil falls in value+  investment:snake oil  = $57+  equity:unrealized profit or loss+.EE+.RE+.PP+All non\-investment postings are assumed to be \[dq]cash flow\[dq],+unless they match \f[CR]\-\-pnl\f[R] query.+Changes in value of your investment due to \[dq]profit and loss\[dq]+postings will be considered as part of your investment return.+.PP+Example: if you use \f[CR]\-\-inv snake \-\-pnl equity:unrealized\f[R],+then postings in the example below would be classifed as:+.IP+.EX+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+.EE+.SS IRR and TWR explained+\[dq]ROI\[dq] stands for \[dq]return on investment\[dq].+Traditionally this was computed as a difference between current value of+investment and its initial value, expressed in percentage of the initial+value.+.PP+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.+.PP+Internal rate of return, or \[dq]IRR\[dq] (also called+\[dq]money\-weighted rate of return\[dq]) 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.+.PP+As mentioned before, in\-flows and out\-flows would be any cash that you+personally put in or withdraw, and for the \[dq]roi\[dq] command, these+are the postings that match the query in the\f[CR]\-\-inv\f[R] argument+and NOT match the query in the\f[CR]\-\-pnl\f[R] argument.+.PP+If you manually record changes in the value of your investment as+transactions that balance them against \[dq]profit and loss\[dq] (or+\[dq]unrealized gains\[dq]) 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.+.PP+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\[aq]t done discounted cash flow analysis before.+Implementation of IRR in hledger should produce results that match the+\f[CR]=XIRR\f[R] formula in Excel.+.PP+Second way to compute rate of return that \f[CR]roi\f[R] command+implements is called \[dq]time\-weighted rate of return\[dq] or+\[dq]TWR\[dq].+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.+.PP+TWR represents your investment as an imaginary \[dq]unit fund\[dq] where+in\-flows/ out\-flows lead to buying or selling \[dq]units\[dq] of your+investment and changes in its value change the value of \[dq]investment+unit\[dq].+Change in \[dq]unit price\[dq] 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.+.PP+References:+.IP \[bu] 2+Explanation of rate of return+.IP \[bu] 2+Explanation of IRR+.IP \[bu] 2+Explanation of TWR+.IP \[bu] 2+IRR vs TWR+.IP \[bu] 2+Examples of computing IRR and TWR and discussion of the limitations of+both metrics+.SH Chart commands+.SS activity+Show an ascii barchart of posting counts per interval.+.PP+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.+.PP+Examples:+.IP+.EX+$ hledger activity \-\-quarterly+2008\-01\-01 **+2008\-04\-01 *******+2008\-07\-01 +2008\-10\-01 **+.EE+.SH Data generation commands+.SS close+(equity)+.PP+\f[CR]close\f[R] generates several kinds of \[dq]closing\[dq] and/or+\[dq]opening\[dq] transactions, useful in certain situations, including+migrating balances to a new journal file, retaining earnings into+equity, consolidating balances, or viewing lots.+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.+.PP+\f[CR]close\f[R] currently has six modes, selected by a single mode+flag:+.SS close \-\-migrate+This is the most common mode.+It prints a \[dq]closing balances\[dq] transaction that zeroes out all+asset and liability balances (by default), and an opposite \[dq]opening+balances\[dq] transaction that restores them again.+The balancing account will be \f[CR]equity:opening/closing balances\f[R]+(or another specified by \f[CR]\-\-close\-acct\f[R] or+\f[CR]\-\-open\-acct\f[R]).+.PP+This is useful when migrating balances to a new journal file at the+start of a new year.+Essentially, you run+\f[CR]hledger close \-\-migrate=NEWYEAR \-e NEWYEAR\f[R] and then copy+the closing transaction to the end of the old file and the opening+transaction to the start of the new file.+The opening transaction sets correct starting balances in the new file+when it is used alone, and the closing transaction keeps balances+correct when you use both old and new files together, by cancelling out+the following opening transaction and preventing buildup of duplicated+opening balances.+Think of the closing/opening pair as \[dq]moving the balances into the+next file\[dq].+.PP+You can close a different set of accounts by providing a query.+Eg if you want to include equity, you can add+\f[CR]assets liabilities equity\f[R] or \f[CR]type:ALE\f[R] arguments.+(The balancing account is always excluded.)+Revenues and expenses usually are not migrated to a new file directly;+see \f[CR]\-\-retain\f[R] below.+.PP+The generated transactions will have a \f[CR]start:\f[R] tag, with its+value set to \f[CR]\-\-migrate\f[R]\[aq]s \f[CR]NEW\f[R] argument if+any, for easier matching or exclusion.+When \f[CR]NEW\f[R] is not specified, it will be inferred if possible by+incrementing a number (eg a year number) within the default+journal\[aq]s main file name.+The other modes behave similarly.+.SS close \-\-close+This prints just the closing balances transaction of+\f[CR]\-\-migrate\f[R].+It is the default behaviour if you specify no mode flag.+Using the customisation options below, you can move balances from any+set of accounts to a different account.+.SS close \-\-open+This prints just the opening balances transaction of+\f[CR]\-\-migrate\f[R].+It is similar to Ledger\[aq]s equity command.+.SS close \-\-assert+This prints a \[dq]closing balances\[dq] transaction (with+\f[CR]balances:\f[R] tag), that just declares balance assertions for the+current balances without changing them.+It could be useful as documention and to guard against changes.+.SS close \-\-assign+This prints an \[dq]opening balances\[dq] transaction that restores the+account balances using balance assignments.+Balance assignments work regardless of any previous balance, so a+preceding closing balances transaction is not needed.+.PP+However, omitting the closing balances transaction would unbalance+equity.+This is relatively harmless for personal reports, but it disturbs the+accounting equation, removing a source of error detection.+So \f[CR]\-\-migrate\f[R] is generally the best way to set to set+balances in new files, for now.+.SS close \-\-retain+This is like \f[CR]\-\-close\f[R] with different defaults: it prints a+\[dq]retain earnings\[dq] transaction (with \f[CR]retain:\f[R] tag),+that transfers revenue and expense balances to+\f[CR]equity:retained earnings\f[R].+.PP+This is a different kind of closing, called \[dq]retaining earnings\[dq]+or \[dq]closing the books\[dq]; it is traditionally performed by+businesses at the end of each accounting period, to consolidate revenues+and expenses into the main equity balance.+(\[dq]Revenues\[dq] and \[dq]expenses\[dq] are actually equity by+another name, kept separate temporarily for reporting purposes.)+.PP+In personal accounting you generally don\[aq]t need to do this, unless+you want the \f[CR]balancesheetequity\f[R] report to show a zero total,+demonstrating that the accounting equation (A\-L=E) is satisfied.+.SS close customisation+In all modes, the following things can be overridden:+.IP \[bu] 2+the accounts to be closed/opened, with account query arguments+.IP \[bu] 2+the balancing account, with \f[CR]\-\-close\-acct=ACCT\f[R] and/or+\f[CR]\-\-open\-acct=ACCT\f[R]+.IP \[bu] 2+the transaction descriptions, with \f[CR]\-\-close\-desc=DESC\f[R] and+\f[CR]\-\-open\-desc=DESC\f[R]+.IP \[bu] 2+the transaction\[aq]s tag value, with a \f[CR]\-\-MODE=NEW\f[R] option+argument+.IP \[bu] 2+the closing/opening dates, with \f[CR]\-e OPENDATE\f[R]+.PP+By default, the closing date is yesterday, or the journal\[aq]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 \f[CR]\-e 2024\f[R] means \[dq]close on 2023\-12\-31, open on+2024\-01\-01\[dq].+.PP+With \f[CR]\-\-x/\-\-explicit\f[R], 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 \f[CR]print \-x\f[R]).+.PP+With \f[CR]\-\-interleaved\f[R], each individual transfer is shown with+source and destination postings next to each other (perhaps useful for+troubleshooting).+.PP+With \f[CR]\-\-show\-costs\f[R], balances\[aq] 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.+\f[CR]close \-\-show\-costs\f[R] is currently the best way to view+investment lots with hledger.+(To move or dispose of lots, see the more capable+\f[CR]hledger\-move\f[R] script.)+.SS close and balance assertions+\f[CR]close\f[R] 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 \f[CR]\-I\f[R], or remove them if you prefer.+.PP+Single\-commodity, subaccount\-exclusive balance assertions+(\f[CR]=\f[R]) are generated by default.+This can be changed with \f[CR]\-\-assertion\-type=\[aq]==*\[aq]\f[R]+(eg).+.PP+When running \f[CR]close\f[R] you should probably avoid using+\f[CR]\-C\f[R], \f[CR]\-R\f[R], \f[CR]status:\f[R] (filtering by status+or realness) or \f[CR]\-\-auto\f[R] (generating postings), since the+generated balance assertions would then require these.+.PP+Transactions with multiple dates (eg posting dates) spanning the file+boundary also can disrupt the balance assertions:+.IP+.EX+2023\-12\-30 a purchase made in december, cleared in january+    expenses:food          5+    assets:bank:checking  \-5  ; date: 2023\-01\-02+.EE+.PP+To solve this you can transfer the money to and from a temporary+account, splitting the multi\-day transaction into two single\-day+transactions:+.IP+.EX+; 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\[aq]s transaction cleared+    equity:pending         5 = 0+    assets:bank:checking  \-5+.EE+.SS close examples+.SS Retain earnings+Record 2022\[aq]s revenues/expenses as retained earnings on+2022\-12\-31, appending the generated transaction to the journal:+.IP+.EX+$ hledger close \-\-retain \-f 2022.journal \-p 2022 >> 2022.journal+.EE+.PP+After this, to see 2022\[aq]s revenues and expenses you must exclude the+retain earnings transaction:+.IP+.EX+$ hledger \-f 2022.journal is not:desc:\[aq]retain earnings\[aq]+.EE+.SS Migrate balances to a new file+Close assets/liabilities on 2022\-12\-31 and re\-open them on+2023\-01\-01:+.IP+.EX+$ 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+.EE+.PP+After this, to see 2022\[aq]s end\-of\-year balances you must exclude+the closing balances transaction:+.IP+.EX+$ hledger \-f 2022.journal bs not:desc:\[aq]closing balances\[aq]+.EE+.PP+For more flexibility, it helps to tag closing and opening transactions+with eg \f[CR]start:NEWYEAR\f[R], then you can ensure correct balances+by excluding all opening/closing transactions except the first, like so:+.IP+.EX+$ hledger bs \-Y \-f 2021.j \-f 2022.j \-f 2023.j expr:\[aq]tag:start=2021 or not tag:start\[aq]+$ hledger bs \-Y \-f 2021.j \-f 2022.j           expr:\[aq]tag:start=2021 or not tag:start\[aq]+$ hledger bs \-Y \-f 2022.j \-f 2023.j           expr:\[aq]tag:start=2022 or not tag:start\[aq]+$ hledger bs \-Y \-f 2021.j                     expr:\[aq]tag:start=2021 or not tag:start\[aq]+$ hledger bs \-Y \-f 2022.j                     expr:\[aq]tag:start=2022 or not tag:start\[aq]+$ hledger bs \-Y \-f 2023.j                     # unclosed file, no query needed+.EE+.SS More detailed close examples+See examples/multi\-year.+.SS rewrite+Print all transactions, rewriting the postings of matched transactions.+For now the only rewrite available is adding new postings, like print+\-\-auto.+.PP+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\[aq]s first posting amount.+.PP+Examples:+.IP+.EX+$ hledger\-rewrite.hs \[ha]income \-\-add\-posting \[aq](liabilities:tax)  *.33  ; income tax\[aq] \-\-add\-posting \[aq](reserve:gifts)  $100\[aq]+$ hledger\-rewrite.hs expenses:gifts \-\-add\-posting \[aq](reserve:gifts)  *\-1\[dq]\[aq]+$ hledger\-rewrite.hs \-f rewrites.hledger+.EE+.PP+rewrites.hledger may consist of entries like:+.IP+.EX+= \[ha]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+.EE+.PP+Note the single quotes to protect the dollar sign from bash, and the two+spaces between account and amount.+.PP+More:+.IP+.EX+$ hledger rewrite \-\- [QUERY]        \-\-add\-posting \[dq]ACCT  AMTEXPR\[dq] ...+$ hledger rewrite \-\- \[ha]income        \-\-add\-posting \[aq](liabilities:tax)  *.33\[aq]+$ hledger rewrite \-\- expenses:gifts \-\-add\-posting \[aq](budget:gifts)  *\-1\[dq]\[aq]+$ hledger rewrite \-\- \[ha]income        \-\-add\-posting \[aq](budget:foreign currency)  *0.25 JPY; diversify\[aq]+.EE+.PP+Argument for \f[CR]\-\-add\-posting\f[R] option is a usual posting of+transaction with an exception for amount specification.+More precisely, you can use \f[CR]\[aq]*\[aq]\f[R] (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\[aq]s commodity.+.SS Re\-write rules in a file+During the run this tool will execute so called \[dq]Automated+Transactions\[dq] found in any journal it process.+I.e instead of specifying this operations in command line you can put+them in a journal file.+.IP+.EX+$ rewrite\-rules.journal+.EE+.PP+Make contents look like this:+.IP+.EX+= \[ha]income+    (liabilities:tax)  *.33++= expenses:gifts+    budget:gifts  *\-1+    assets:budget  *1+.EE+.PP+Note that \f[CR]\[aq]=\[aq]\f[R] (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.+.IP+.EX+$ hledger rewrite \-\- \-f input.journal \-f rewrite\-rules.journal > rewritten\-tidy\-output.journal+.EE+.PP+This is something similar to the commands pipeline:+.IP+.EX+$ hledger rewrite \-\- \-f input.journal \[aq]\[ha]income\[aq] \-\-add\-posting \[aq](liabilities:tax)  *.33\[aq] \[rs]+  | hledger rewrite \-\- \-f \- expenses:gifts      \-\-add\-posting \[aq]budget:gifts  *\-1\[aq]       \[rs]+                                                \-\-add\-posting \[aq]assets:budget  *1\[aq]       \[rs]+  > rewritten\-tidy\-output.journal+.EE+.PP+It is important to understand that relative order of such entries in+journal is important.+You can re\-use result of previously added postings.+.SS Diff output format+To use this tool for batch modification of your journal files you may+find useful output in form of unified diff.+.IP+.EX+$ hledger rewrite \-\- \-\-diff \-f examples/sample.journal \[aq]\[ha]income\[aq] \-\-add\-posting \[aq](liabilities:tax)  *.33\[aq]+.EE+.PP+Output might look like:+.IP+.EX+\-\-\- /tmp/examples/sample.journal++++ /tmp/examples/sample.journal+\[at]\[at] \-18,3 +18,4 \[at]\[at]+ 2008/01/01 income+\-    assets:bank:checking  $1++    assets:bank:checking            $1+     income:salary++    (liabilities:tax)                0+\[at]\[at] \-22,3 +23,4 \[at]\[at]+ 2008/06/01 gift+\-    assets:bank:checking  $1++    assets:bank:checking            $1+     income:gifts++    (liabilities:tax)                0+.EE+.PP+If you\[aq]ll pass this through \f[CR]patch\f[R] tool you\[aq]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 \f[CR]\-\-file\f[R] options and \f[CR]include\f[R]+directives inside of these files.+.PP+Be careful.+Whole transaction being re\-formatted in a style of output from+\f[CR]hledger print\f[R].+.PP+See also:+.PP+https://github.com/simonmichael/hledger/issues/99+.SS rewrite vs. print \-\-auto+This command predates print \-\-auto, and currently does much the same+thing, but with these differences:+.IP \[bu] 2+with multiple files, rewrite lets rules in any file affect all other+files.+print \-\-auto uses standard directive scoping; rules affect only child+files.+.IP \[bu] 2+rewrite\[aq]s query limits which transactions can be rewritten; all are+printed.+print \-\-auto\[aq]s query limits which transactions are printed.+.IP \[bu] 2+rewrite applies rules specified on command line or in the journal.+print \-\-auto applies rules specified in the journal.+.SH Maintenance commands+.SS check+Check for various kinds of errors in your data.+.PP+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 \f[CR]\-\-strict\f[R]+mode; or you can run any of them on demand by providing them as+arguments to the \f[CR]check\f[R] command.+\f[CR]check\f[R] produces no output and a zero exit code if all is well.+Eg:+.IP+.EX+hledger check                      # run basic checks+hledger check \-s                   # run basic and strict checks+hledger check ordereddates payees  # run basic checks and two others+.EE+.PP+If you are an Emacs user, you can also configure flycheck\-hledger to+run these checks, providing instant feedback as you edit the journal.+.PP+Here are the checks currently available.+Generally, they are performed in the order they are shown here (and only+the first failure is reported).+.SS Basic checks+These important checks are performed by default, by almost all hledger+commands:+.IP \[bu] 2+\f[B]parseable\f[R] \- 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.+.IP \[bu] 2+\f[B]autobalanced\f[R] \- 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.+.IP \[bu] 2+\f[B]assertions\f[R] \- 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+\f[CR]\-I\f[R]/\f[CR]\-\-ignore\-assertions\f[R] (unless overridden with+\f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R] or+\f[CR]hledger check assertions\f[R]).+.SS Strict checks+These additional checks are performed by any command when the+\f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R] 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:+.IP \[bu] 2+\f[B]balanced\f[R] \- like \f[CR]autobalanced\f[R], but in conversion+transactions, costs must be written explicitly.+This ensures some redundancy in the entry, which helps prevent typos.+.IP \[bu] 2+\f[B]commodities\f[R] \- all commodity symbols used must be declared.+This guards against mistyping or omitting commodity symbols.+.IP \[bu] 2+\f[B]accounts\f[R] \- all account names used must be declared.+This prevents the use of mis\-spelled or outdated account names.+.SS Other checks+These other checks are not wanted by everyone, but can be run using the+\f[CR]check\f[R] command:+.IP \[bu] 2+\f[B]ordereddates\f[R] \- 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 \f[CR]hledger check \-s ordereddates\f[R].+When enabled, this check is performed early, before balance assertions+(because copy\-pasted dates are often the root cause of balance+assertion failures).+.IP \[bu] 2+\f[B]payees\f[R] \- 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.+.IP \[bu] 2+\f[B]tags\f[R] \- all tags used by transactions must be declared.+This prevents mistyped tag names.+.IP \[bu] 2+\f[B]recentassertions\f[R] \- 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.+\f[CR]close \-\-assert\f[R] can be helpful.+(The older balance assertions become redundant; you can remove them+periodically, or leave them in place, perhaps commented, as+documentation.)+.IP \[bu] 2+\f[B]uniqueleafnames\f[R] \- no two accounts may have the same leaf+name.+The leaf name is the last colon\-separated part of an account name, eg+\f[CR]checking\f[R] in \f[CR]assets:bank:checking\f[R].+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.+.SS 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/:+.IP \[bu] 2+\f[B]hledger\-check\-tagfiles\f[R] \- all tag values containing / (a+forward slash) exist as file paths+.IP \[bu] 2+\f[B]hledger\-check\-fancyassertions\f[R] \- more complex balance+assertions are passing+.SS diff+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.+.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+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.+.PP+Examples:+.IP+.EX+$ 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:+.EE+.SS test+Run built\-in unit tests.+.PP+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.+.PP+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!+.PP+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:+.IP+.EX+$ hledger test \-\- \-pData.Amount \-\-color=never+.EE+.PP+For help on these, see https://github.com/feuerbach/tasty#options+(\f[CR]\-\- \-\-help\f[R] currently doesn\[aq]t show them).+.PP+.SH PART 5: COMMON TASKS+Here are some quick examples of how to do some basic tasks with hledger.+.SH Getting help+Here\[aq]s how to list commands and view options and command docs:+.IP+.EX+$ hledger                # show available commands+$ hledger \-\-help         # show common options+$ hledger CMD \-\-help     # show CMD\[aq]s options, common options and CMD\[aq]s documentation+.EE+.PP+You can also view your hledger version\[aq]s manual in several formats+by using the help command.+Eg:+.IP+.EX+$ 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+.EE+.PP+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.+.SH 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:+.IP \[bu] 2+command\-specific options must go after the command (it\[aq]s fine to+put common options there too: \f[CR]hledger CMD OPTS ARGS\f[R])+.IP \[bu] 2+running add\-on executables directly simplifies command line parsing+(\f[CR]hledger\-ui OPTS ARGS\f[R])+.IP \[bu] 2+enclose \[dq]problematic\[dq] args in single quotes+.IP \[bu] 2+if needed, also add a backslash to hide regular expression+metacharacters from the shell+.IP \[bu] 2+to see how a misbehaving command line is being parsed, add+\f[CR]\-\-debug=2\f[R].+.SH Starting a journal file+hledger looks for your accounting data in a journal file,+\f[CR]$HOME/.hledger.journal\f[R] by default:+.IP+.EX+$ hledger stats+The hledger journal file \[dq]/Users/simon/.hledger.journal\[dq] was not found.+Please create it first, eg with \[dq]hledger add\[dq] or a text editor.+Or, specify an existing journal file with \-f or LEDGER_FILE.+.EE+.PP+You can override this by setting the \f[CR]LEDGER_FILE\f[R] environment+variable (see below).+It\[aq]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:+.IP+.EX+$ mkdir \[ti]/finance+$ cd \[ti]/finance+$ git init+Initialized empty Git repository in /Users/simon/finance/.git/+$ touch 2023.journal+$ echo \[dq]export LEDGER_FILE=$HOME/finance/2023.journal\[dq] >> \[ti]/.profile+$ source \[ti]/.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 ()+.EE+.SH Setting LEDGER_FILE+How to set \f[CR]LEDGER_FILE\f[R] permanently depends on your setup:+.PP+On unix and mac, running these commands in the terminal will work for+many people; adapt as needed:+.IP+.EX+$ echo \[aq]export LEDGER_FILE=\[ti]/finance/2023.journal\[aq] >> \[ti]/.profile+$ source \[ti]/.profile+.EE+.PP+When correctly configured, in a new terminal window+\f[CR]env | grep LEDGER_FILE\f[R] will show your file, and so will+\f[CR]hledger files\f[R].+.PP+On mac, this additional step might be helpful for GUI applications (like+Emacs started from the dock): add an entry to+\f[CR]\[ti]/.MacOSX/environment.plist\f[R] like+.IP+.EX+{+  \[dq]LEDGER_FILE\[dq] : \[dq]\[ti]/finance/2023.journal\[dq]+}+.EE+.PP+and then run \f[CR]killall Dock\f[R] in a terminal window (or restart+the machine).+.PP+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):+.IP+.EX+> CD+> MKDIR finance+> SETX LEDGER_FILE \[dq]C:\[rs]Users\[rs]USERNAME\[rs]finance\[rs]2023.journal\[dq]+.EE+.SH 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..).+.PP+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.+.PP+Add an opening balances transaction to the journal, declaring the+balances on this date.+Here are two ways to do it:+.IP \[bu] 2+The first way: open the journal in any text editor and save an entry+like this:+.RS 2+.IP+.EX+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+.EE+.PP+These are start\-of\-day balances, ie whatever was in the account at the+end of the previous day.+.PP+The * after the date is an optional status flag.+Here it means \[dq]cleared & confirmed\[dq].+.PP+The currency symbols are optional, but usually a good idea as you\[aq]ll+be dealing with multiple currencies sooner or later.+.PP+The = amounts are optional balance assertions, providing extra error+checking.+.RE+.IP \[bu] 2+The second way: run \f[CR]hledger add\f[R] and follow the prompts to+record a similar transaction:+.RS 2+.IP+.EX+$ 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]: .+.EE+.RE+.PP+If you\[aq]re using version control, this could be a good time to commit+the journal.+Eg:+.IP+.EX+$ git commit \-m \[aq]initial balances\[aq] 2023.journal+.EE+.SH 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.+.PP+Here are some simple transactions, see the hledger_journal(5) manual and+hledger.org for more ideas:+.IP+.EX+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+.EE+.SH Reconciling+Periodically you should reconcile \- compare your hledger\-reported+balances against external sources of truth, like bank statements or your+bank\[aq]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.+.PP+A typical workflow:+.IP "1." 3+Reconcile cash.+Count what\[aq]s in your wallet.+Compare with what hledger reports (\f[CR]hledger bal cash\f[R]).+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 (\f[CR]hledger reg cash\f[R]).+If you can\[aq]t find the error, add an adjustment transaction.+Eg if you have $105 after the above, and can\[aq]t explain the missing+$2, it could be:+.RS 4+.IP+.EX+2023\-01\-16 * adjust cash+    assets:cash    $\-2 = $105+    expenses:misc+.EE+.RE+.IP "2." 3+Reconcile checking.+Log in to your bank\[aq]s website.+Compare today\[aq]s (cleared) balance with hledger\[aq]s cleared balance+(\f[CR]hledger bal checking \-C\f[R]).+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+\f[CR]hledger reg checking \-C\f[R].+This will be easier if you generally record transaction dates quite+similar to your bank\[aq]s clearing dates.+.IP "3." 3+Repeat for other asset/liability accounts.+.PP+Tip: instead of the register command, use hledger\-ui to see a+live\-updating register while you edit the journal:+\f[CR]hledger\-ui \-\-watch \-\-register checking \-C\f[R]+.PP+After reconciling, it could be a good time to mark the reconciled+transactions\[aq] status as \[dq]cleared and confirmed\[dq], if you want+to track that, by adding the \f[CR]*\f[R] marker.+Eg in the paycheck transaction above, insert \f[CR]*\f[R] between+\f[CR]2023\-01\-15\f[R] and \f[CR]paycheck\f[R]+.PP+If you\[aq]re using version control, this can be another good time to+commit:+.IP+.EX+$ git commit \-m \[aq]txns\[aq] 2023.journal+.EE+.SH Reporting+Here are some basic reports.+.PP+Show all transactions:+.IP+.EX+$ 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+.EE+.PP+Show account names, and their hierarchy:+.IP+.EX+$ hledger accounts \-\-tree+assets+  bank+    checking+    savings+  cash+equity+  opening/closing balances+expenses+  food+  misc+income+  gifts+  salary+liabilities+  creditcard+.EE+.PP+Show all account totals:+.IP+.EX+$ 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+.EE+.PP+Show only asset and liability balances, as a flat list, limited to depth+2:+.IP+.EX+$ hledger bal assets liabilities \-2+               $4000  assets:bank+                $105  assets:cash+                $\-50  liabilities:creditcard+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+               $4055+.EE+.PP+Show the same thing without negative numbers, formatted as a simple+balance sheet:+.IP+.EX+$ 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 +.EE+.PP+The final total is your \[dq]net worth\[dq] on the end date.+(Or use \f[CR]bse\f[R] for a full balance sheet with equity.)+.PP+Show income and expense totals, formatted as an income statement:+.IP+.EX+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 +.EE+.PP+The final total is your net income during this period.+.PP+Show transactions affecting your wallet, with running total:+.IP+.EX+$ 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+.EE+.PP+Show weekly posting counts as a bar chart:+.IP+.EX+$ hledger activity \-W+2019\-12\-30 *****+2023\-01\-06 ****+2023\-01\-13 ****+.EE+.SH 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\[aq]t slow down or clutter your reports, and to help ensure the integrity of your accounting history.