hledger 1.24.99 → 1.25

raw patch · 29 files changed

+36865/−34793 lines, 29 filesdep ~aesondep ~hledger-libPVP ok

version bump matches the API change (PVP)

Dependency ranges changed: aeson, hledger-lib

API changes (from Hackage documentation)

Files

• CHANGES.md +119/−7
• Hledger/Cli/Anon.hs +6/−3
• Hledger/Cli/CliOptions.hs +3/−1
• Hledger/Cli/Commands/Accounts.hs +24/−10
• Hledger/Cli/Commands/Accounts.txt +3/−0
• Hledger/Cli/Commands/Activity.hs +9/−9
• Hledger/Cli/Commands/Aregister.hs +3/−2
• Hledger/Cli/Commands/Balance.hs +11/−13
• Hledger/Cli/Commands/Close.hs +6/−6
• Hledger/Cli/Commands/Print.hs +10/−2
• Hledger/Cli/Commands/Print.txt +1/−0
• Hledger/Cli/Commands/Rewrite.hs +1/−1
• Hledger/Cli/Commands/Roi.hs +15/−22
• Hledger/Cli/Commands/Roi.txt +9/−5
• Hledger/Cli/Commands/Stats.hs +1/−2
• Hledger/Cli/CompoundBalanceCommand.hs +4/−4
• embeddedfiles/hledger-ui.1 +2/−2
• embeddedfiles/hledger-ui.info +29/−29
• embeddedfiles/hledger-ui.txt +2/−2
• embeddedfiles/hledger-web.1 +2/−2
• embeddedfiles/hledger-web.info +17/−17
• embeddedfiles/hledger-web.txt +2/−2
• embeddedfiles/hledger.1 +438/−90
• embeddedfiles/hledger.info +9955/−9616
• embeddedfiles/hledger.txt +7896/−7616
• hledger.1 +438/−90
• hledger.cabal +8/−8
• hledger.info +9955/−9616
• hledger.txt +7896/−7616

@@ -9,21 +9,133 @@ User-visible changes in the hledger command line tool and library.  -# a98e6125f+# 1.25 2022-03-04 +Breaking changes++- Journal format's `account NAME  TYPECODE` syntax, deprecated in 1.13, has been dropped.+  Please use `account NAME  ; type:TYPECODE` instead.+  (Stephen Morgan)++- The rule for auto-detecting "cash" (liquid asset) accounts from account names+  for the `cashflow` report has been simplified. +  If you have been using the cashflow report, without explicitly declaring Cash accounts,+  you might notice a change, and might need to declare your Cash accounts explicitly+  (by adding `type:C` tags to top-level cash account directives).+ Features +- The new `type:TYPECODES` query matches accounts by their accounting type.+  Account types are declared with a `type:` tag in account directives,+  or inferred from common english account names, or inherited from parent accounts,+  as described at [Declaring accounts > Account types].+  This generalises the account type detection of `balancesheet`, `incomestatement` etc.,+  so you can now select accounts by type without needing fragile account name regexps.+  Also, the `accounts` command has a new `--types` flag to show account types.+  Eg:++      hledger bal type:AL  # balance report showing assets and liabilities+      hledger reg type:x   # register of all expenses+      hledger acc --types  # list accounts and their types++  ([#1820](https://github.com/simonmichael/hledger/issues/1820), +  [#1822](https://github.com/simonmichael/hledger/issues/1822)) +  (Simon Michael, Stephen Morgan)++- The `tag:` query can now also match account tags, as defined in account directives.+  Subaccounts inherit tags from their parents.+  Accounts, postings and transactions can be filtered by account tag.+  ([#1817](https://github.com/simonmichael/hledger/issues/1817))++- The new `--infer-equity` flag replaces the `@`/`@@` price notation in commodity+  conversion transactions with more correct equity postings (when not using `-B/--cost`).+  This makes these transactions fully balanced, and preserves the accounting equation.+  For example:++      2000-01-01+        a             1 AAA @@ 2 BBB+        b            -2 BBB++      $ hledger print --infer-equity+      2000-01-01+        a                               1 AAA+        equity:conversion:AAA-BBB:AAA  -1 AAA+        equity:conversion:AAA-BBB:BBB   2 BBB+        b                              -2 BBB++  +  `equity:conversion` is the account used by default. To use a different account,+  declare it with an account directive and the new `V` (`Conversion`) account type.+  Eg:+  +      account Equity:Trading    ; type:V++  ([#1554](https://github.com/simonmichael/hledger/issues/1554)) (Stephen Morgan, Simon Michael)+ - Normalised, easy-to-process "tidy" CSV data can now be generated with `--layout tidy -O csv`.   In tidy data, every variable is a column and each row represents a single data point    (cf <https://vita.had.co.nz/papers/tidy-data.html>).-  (#1768, #1773, #1775) (Stephen Morgan)+  ([#1768](https://github.com/simonmichael/hledger/issues/1768), +  [#1773](https://github.com/simonmichael/hledger/issues/1773), +  [#1775](https://github.com/simonmichael/hledger/issues/1775)) +  (Stephen Morgan)  Improvements +- Strict mode (`-s/--strict`) now also checks periodic transactions (`--forecast`) +  and auto postings (`--auto`). +  ([#1810](https://github.com/simonmichael/hledger/issues/1810)) (Stephen Morgan)++- `hledger check commodities` now always accepts zero amounts which have no commodity symbol. +  ([#1767](https://github.com/simonmichael/hledger/issues/1767)) (Stephen Morgan)++- Relative [smart dates](hledger.html#smart-dates) may now specify an arbitrary number of some period into the future or past).+  Some examples:+  - `in 5 days`+  - `in -6 months`+  - `5 weeks ahead`+  - `2 quarters ago`+  +  (Stephen Morgan)+ - CSV output now always disables digit group marks (eg, thousands separators),-  for better machine readability. -  (#1771) (Stephen Morgan)+  making it more machine readable by default. +  ([#1771](https://github.com/simonmichael/hledger/issues/1771)) (Stephen Morgan) +- Unicode may now be used in field names/references in CSV rules files.+  ([#1809](https://github.com/simonmichael/hledger/issues/1809)) (Stephen Morgan)++- Error messages improved:+  - Balance assignments+  - aregister+  - Command line parsing (less "user error")++Fixes++- `--layout=bare` no longer shows a commodity symbol for zero amounts. +  ([#1789](https://github.com/simonmichael/hledger/issues/1789)) (Stephen Morgan)++- `balance --budget` no longer elides boring parents of unbudgeted accounts +  if they have a budget. +  ([#1800](https://github.com/simonmichael/hledger/issues/1800)) (Stephen Morgan)++- `roi` now reports TWR correctly++  - when there are several PnL changes occurring on a single day+  - and also when investment is fully sold/withdrawn/discounted at the end of a particular reporting period.++  ([#1791](https://github.com/simonmichael/hledger/issues/1791)) (Dmitry Astapov)++Documentation++- There is a new CONVERSION & COST section, replacing COSTING. +  ([#1554](https://github.com/simonmichael/hledger/issues/1554))++- Some problematic interactions of account aliases with other features have been noted. +  ([#1788](https://github.com/simonmichael/hledger/issues/1788))++[Declaring accounts > Account types]: (https://hledger.org/hledger.html#account-types+ # 1.24.1 2021-12-10  Fixes@@ -35,9 +147,9 @@  API changes: -- new type synonyms ProgramName, PackageVersion, VersionString-- versionStringForProgname -> versionString with extra argument-- versionStringFor -> versionStringWith with extra argument+- new type synonyms ProgramName, PackageVersion, VersionString+- versionStringForProgname -> versionString with extra argument+- versionStringFor -> versionStringWith with extra argument  # 1.24 2021-12-01 

@@ -19,6 +19,7 @@ import qualified Data.Text as T  import Hledger.Data+import Data.Map (mapKeys)  class Anon a where     -- | Consistent converter to structure with sensitive data anonymized@@ -27,9 +28,11 @@ instance Anon Journal where     -- Apply the anonymisation transformation on a journal after finalisation     anon j = j { jtxns = map anon . jtxns $ j-               , jparseparentaccounts = map anonAccount $ jparseparentaccounts j-               , jparsealiases = []  -- already applied-               , jdeclaredaccounts = map (first anon) $ jdeclaredaccounts j+               , jparseparentaccounts  = map anonAccount $ jparseparentaccounts j+               , jparsealiases         = []  -- already applied+               , jdeclaredaccounts     = map (first anon) $ jdeclaredaccounts j+               , jdeclaredaccounttags  = mapKeys anon $ jdeclaredaccounttags j+               , jdeclaredaccounttypes = (map anon) <$> jdeclaredaccounttypes j                }  instance Anon Posting where

@@ -181,6 +181,8 @@      ,"'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")+    "in conversion transactions, replace costs (transaction prices) with equity postings, to keep the transactions balanced"      -- history of this flag so far, lest we be confused:   --  originally --infer-value@@ -487,7 +489,7 @@               Just d  -> fromRight (error' $ "Unable to parse date \"" ++ d ++ "\"") -- PARTIAL:                          $ fixSmartDateStrEither' currentDay (T.pack d)   let iopts = rawOptsToInputOpts day rawopts-  rspec <- either fail pure $ rawOptsToReportSpec day rawopts  -- PARTIAL:+  rspec <- either error' pure $ rawOptsToReportSpec day rawopts  -- PARTIAL:   mcolumns <- readMay <$> getEnvSafe "COLUMNS"   mtermwidth <- #ifdef mingw32_HOST_OS

@@ -27,6 +27,7 @@  import Hledger import Hledger.Cli.CliOptions+import Control.Monad (forM_)   -- | Command line options for this command.@@ -34,6 +35,7 @@   $(embedFileRelative "Hledger/Cli/Commands/Accounts.txt")   ([flagNone ["declared"] (setboolopt "declared") "show account names declared with account directives"   ,flagNone ["used"] (setboolopt "used") "show account names referenced by transactions"+  ,flagNone ["types"] (setboolopt "types") "also show accounts' types, when known"   ]   ++ flattreeflags False ++   [flagReq  ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "flat mode: omit N leading account name parts"@@ -50,12 +52,16 @@   let tree     = tree_ ropts       declared = boolopt "declared" rawopts       used     = boolopt "used"     rawopts+      types    = boolopt "types"    rawopts       -- a depth limit will clip and exclude account names later, but we don't want to exclude accounts at this stage       nodepthq = dbg1 "nodepthq" $ filterQuery (not . queryIsDepth) query       -- just the acct: part of the query will be reapplied later, after clipping       acctq    = dbg1 "acctq" $ filterQuery queryIsAcct query       depth    = dbg1 "depth" $ queryDepth $ filterQuery queryIsDepth query-      matcheddeclaredaccts = dbg1 "matcheddeclaredaccts" $ filter (matchesAccount nodepthq) $ map fst $ jdeclaredaccounts j+      matcheddeclaredaccts =+        dbg1 "matcheddeclaredaccts" $+        filter (matchesAccountExtra (journalAccountType j) (journalInheritedAccountTags j) nodepthq)+          $ map fst $ jdeclaredaccounts j       matchedusedaccts     = dbg5 "matchedusedaccts" $ map paccount $ journalPostings $ filterJournalPostings nodepthq j       accts                = dbg5 "accts to show" $ -- no need to nub/sort, accountTree will         if | declared     && not used -> matcheddeclaredaccts@@ -74,12 +80,20 @@         map (clipAccountName depth) $  -- clip at depth if specified         sortedaccts -  -- 4. print what remains as a list or tree, maybe applying --drop in the former case-  mapM_ (T.putStrLn . render) clippedaccts-    where-      render a = case accountlistmode_ ropts of-          ALTree -> T.replicate indent " " <> accountLeafName droppedName-          ALFlat -> droppedName-        where-          indent = 2 * (max 0 (accountNameLevel a - drop_ ropts) - 1)-          droppedName = accountNameDrop (drop_ ropts) a+  -- 4. print what remains as a list or tree, maybe applying --drop in the former case.+  -- With --types, also show the account type.+  let+    -- some contortions here to show types nicely aligned+    showName a = case accountlistmode_ ropts of+      ALTree -> indent <> accountLeafName droppedName+      ALFlat -> droppedName+      where+        indent      = T.replicate (2 * (max 0 (accountNameLevel a - drop_ ropts) - 1)) " "+        droppedName = accountNameDrop (drop_ ropts) a+    showType a +      | types     = spacer <> "    ; type: " <> maybe "" (T.pack . show) (journalAccountType j a)+      | otherwise = ""+      where+        spacer = T.replicate (maxwidth - T.length (showName a)) " "+    maxwidth = maximum $ map (T.length . showName) clippedaccts+  forM_ clippedaccts $ \a -> T.putStrLn $ showName a <> showType a

@@ -11,6 +11,9 @@ you can add --drop N to omit the first few account name components. Account names can be depth-clipped with depth:N or --depth N or -N. +With --types, it also shows each account's type, if it's known. (See+Declaring accounts > Account types.)+ Examples:  $ hledger accounts

@@ -9,9 +9,9 @@ module Hledger.Cli.Commands.Activity where -import Data.List-import Data.Maybe-import Text.Printf+import Data.List (sortOn)+import Text.Printf (printf)+import Lens.Micro ((^.), set)  import Hledger import Hledger.Cli.CliOptions@@ -31,19 +31,19 @@ activity CliOpts{reportspec_=rspec} j = putStr $ showHistogram rspec j  showHistogram :: ReportSpec -> Journal -> String-showHistogram ReportSpec{_rsQuery=q,_rsReportOpts=ReportOpts{interval_=i,date2_=date2}} j =+showHistogram rspec@ReportSpec{_rsQuery=q} j =     concatMap (printDayWith countBar) spanps   where-    interval | i == NoInterval = Days 1-             | otherwise = i-    span' = queryDateSpan date2 q `spanDefaultsFrom` journalDateSpan date2 j-    spans = filter (DateSpan Nothing Nothing /=) $ splitSpan interval span'+    spans = filter (DateSpan Nothing Nothing /=) . snd . reportSpan j $ case rspec ^. interval of+      NoInterval -> set interval (Days 1) rspec+      _ -> rspec     spanps = [(s, filter (isPostingInDateSpan s) ps) | s <- spans]     -- same as Register     -- should count transactions, not postings ?     -- ps = sortBy (comparing postingDate) $ filterempties $ filter matchapats $ filterdepth $ journalPostings j     ps = sortOn postingDate $ filter (q `matchesPosting`) $ journalPostings j -printDayWith f (DateSpan b _, ps) = printf "%s %s\n" (show $ fromJust b) (f ps)+printDayWith f (DateSpan (Just b) _, ps) = printf "%s %s\n" (show b) (f ps)+printDayWith _ _ = error "Expected start date for DateSpan"  -- PARTIAL:  countBar ps = replicate (length ps) barchar

@@ -69,11 +69,12 @@ aregister :: CliOpts -> Journal -> IO () aregister opts@CliOpts{rawopts_=rawopts,reportspec_=rspec} j = do   -- the first argument specifies the account, any remaining arguments are a filter query+  let help = "aregister needs an ACCTPAT argument to select an account"   (apat,querystring) <- case listofstringopt "args" rawopts of-      []     -> fail "aregister needs an account, please provide an account name or pattern"+      []     -> error' $ help <> ".\nPlease provide an account name or a (case-insensitive, infix, regexp) pattern."       (a:as) -> return (a, map T.pack as)   let-    acct = fromMaybe (error' $ show apat++" did not match any account")   -- PARTIAL:+    acct = fromMaybe (error' $ help <> ",\nbut " ++ show apat++" did not match any account.")   -- PARTIAL:            . firstMatch $ journalAccountNamesDeclaredOrImplied j     firstMatch = case toRegexCI $ T.pack apat of         Right re -> find (regexMatchText re)

@@ -259,7 +259,7 @@ ) where  import Data.Default (def)-import Data.List (transpose, foldl', transpose)+import Data.List (transpose, transpose) import qualified Data.Set as S import Data.Maybe (fromMaybe) import qualified Data.Text as T@@ -340,7 +340,7 @@ balance :: CliOpts -> Journal -> IO () balance opts@CliOpts{reportspec_=rspec} j = case balancecalc_ of     CalcBudget -> do  -- single or multi period budget report-      let reportspan = reportSpan j rspec+      let reportspan = fst $ reportSpan j rspec           budgetreport = budgetReport rspec (balancingopts_ $ inputopts_ opts) reportspan j           render = case fmt of             "txt"  -> budgetReportAsText ropts@@ -456,7 +456,7 @@         , Cell TopLeft (fmap wbFromText cs)         , Cell TopLeft (replicate (length damts - 1) mempty ++ [wbFromText dispname]) ]       where dopts = oneLine{displayColour=color_ opts, displayOrder=Just cs}-            cs    = S.toList $ maCommodities amt+            cs    = if mixedAmountLooksZero amt then [""] else S.toList $ maCommodities amt             dispname = T.replicate ((depth - 1) * 2) " " <> acctname             damts = showMixedAmountLinesB dopts amt     lines = fmap render items@@ -652,9 +652,9 @@         (_,               Cumulative ) -> "Ending balances (cumulative)"         (_,               Historical)  -> "Ending balances (historical)"     valuationdesc =-        (case cost_ of-            Cost   -> ", converted to cost"-            NoCost -> "")+        (case conversionop_ of+            Just ToCost -> ", converted to cost"+            _           -> "")         <> (case value_ of             Just (AtThen _mc)    -> ", valued at posting date"             Just (AtEnd _mc) | changingValuation -> ""@@ -703,14 +703,14 @@ multiBalanceRowAsWbs :: AmountDisplayOpts -> ReportOpts -> [DateSpan] -> PeriodicReportRow a MixedAmount -> [[WideBuilder]] multiBalanceRowAsWbs bopts ReportOpts{..} colspans (PeriodicReportRow _ as rowtot rowavg) =     case layout_ of-      LayoutWide width -> [fmap (showMixedAmountB bopts{displayMaxWidth=width}) all]+      LayoutWide width -> [fmap (showMixedAmountB bopts{displayMaxWidth=width}) allamts]       LayoutTall       -> paddedTranspose mempty                            . fmap (showMixedAmountLinesB bopts{displayMaxWidth=Nothing})-                           $ all+                           $ allamts       LayoutBare       -> zipWith (:) (fmap wbFromText cs)  -- add symbols                            . transpose                         -- each row becomes a list of Text quantities                            . fmap (showMixedAmountLinesB bopts{displayOrder=Just cs, displayMinWidth=Nothing})-                           $ all+                           $ allamts       LayoutTidy       -> concat                            . zipWith (map . addDateColumns) colspans                            . fmap ( zipWith (\c a -> [wbFromText c, a]) cs@@ -719,10 +719,8 @@                                  -- complicates the data representation and can be easily calculated   where     totalscolumn = row_total_ && balanceaccum_ `notElem` [Cumulative, Historical]-    cs = S.toList . foldl' S.union mempty $ fmap maCommodities all-    all = as-        ++ [rowtot | totalscolumn && not (null as)]-        ++ [rowavg | average_     && not (null as)]+    cs = if all mixedAmountLooksZero allamts then [""] else S.toList $ foldMap maCommodities allamts+    allamts = as ++ [rowtot | totalscolumn && not (null as)] ++ [rowavg | average_ && not (null as)]     addDateColumns span@(DateSpan s e) = (wbFromText (showDateSpan span) :)                                        . (wbFromText (maybe "" showDate s) :)                                        . (wbFromText (maybe "" (showDate . addDays (-1)) e) :)

@@ -48,9 +48,8 @@  -- debugger, beware: close is incredibly devious. simple rules combine to make a horrid maze. -- tests are in hledger/test/close.test.-close CliOpts{rawopts_=rawopts, reportspec_=rspec} j = do+close CliOpts{rawopts_=rawopts, reportspec_=rspec'} j = do   let-    today = _rsDay rspec     -- show opening entry, closing entry, or (default) both ?     (opening, closing) =       case (boolopt "open" rawopts, boolopt "close" rawopts) of@@ -72,6 +71,9 @@         (Nothing, Just o)  -> (o, o)         (Nothing, Nothing) -> (T.pack defclosingacct, T.pack defopeningacct) +    ropts = (_rsReportOpts rspec'){balanceaccum_=Historical, accountlistmode_=ALFlat}+    rspec = setDefaultConversionOp NoConversionOp rspec'{_rsReportOpts=ropts}+     -- dates of the closing and opening transactions     --     -- Close.md:@@ -90,7 +92,7 @@     -- - `-e 2021`"     --     q = _rsQuery rspec-    yesterday = addDays (-1) today+    yesterday = addDays (-1) $ _rsDay rspec     yesterdayorjournalend = case journalLastDay False j of       Just journalend -> max yesterday journalend       Nothing         -> yesterday@@ -102,9 +104,7 @@     explicit = boolopt "explicit" rawopts      -- the balances to close-    ropts = (_rsReportOpts rspec){balanceaccum_=Historical, accountlistmode_=ALFlat}-    rspec_ = rspec{_rsReportOpts=ropts}-    (acctbals',_) = balanceReport rspec_ j+    (acctbals',_) = balanceReport rspec j     acctbals = map (\(a,_,_,b) -> (a, if show_costs_ ropts then b else mixedAmountStripPrices b)) acctbals'     totalamt = maSum $ map snd acctbals 

@@ -21,7 +21,7 @@ import qualified Data.Text.IO as T import qualified Data.Text.Lazy as TL import qualified Data.Text.Lazy.Builder as TB-import Lens.Micro (_Just, has)+import Lens.Micro ((^.), _Just, has) import System.Console.CmdArgs.Explicit  import Hledger@@ -37,6 +37,8 @@     ("show the transaction whose description is most similar to "++arg++", and is most recent")   ,flagNone ["explicit","x"] (setboolopt "explicit")     "show all amounts explicitly"+  ,flagNone ["show-costs"] (setboolopt "show-costs")+    "show transaction prices even with conversion postings"   ,flagNone ["new"] (setboolopt "new")     "show only newer-dated transactions added in each file since last run"   ,outputFormatFlag ["txt","csv","json","sql"]@@ -72,7 +74,8 @@            | otherwise   = error' $ unsupportedOutputFormatError fmt  -- PARTIAL:  entriesReportAsText :: CliOpts -> EntriesReport -> TL.Text-entriesReportAsText opts = TB.toLazyText . foldMap (TB.fromText . showTransaction . whichtxn)+entriesReportAsText opts =+    TB.toLazyText . foldMap (TB.fromText . showTransaction . maybeStripPrices . whichtxn)   where     whichtxn       -- With -x, use the fully-inferred txn with all amounts & txn prices explicit.@@ -84,6 +87,11 @@       | has (value . _Just) opts = id       -- By default, use the original as-written-in-the-journal txn.       | otherwise = originalTransaction+    maybeStripPrices+      -- Strip prices when inferring equity, unless the show_costs_  is set+      | opts ^. infer_equity && not (opts ^. show_costs) =+          transactionTransformPostings postingStripPrices+      | otherwise = id  -- Replace this transaction's postings with the original postings if any, but keep the -- current possibly rewritten account names, and the inferred values of any auto postings

@@ -56,6 +56,7 @@ -   Valuation affects posting amounts but not balance assertion or     balance assignment amounts, potentially causing those to fail. -   Auto postings can generate postings with too many missing amounts.+-   Account aliases can generate bad account names.  Normally, the journal entry's explicit or implicit amount style is preserved. For example, when an amount is omitted in the journal, it

@@ -41,7 +41,7 @@   -- rewrite matched transactions   let today = _rsDay rspec   let modifiers = transactionModifierFromOpts opts : jtxnmodifiers j-  let j' = j{jtxns=either error' id $ modifyTransactions mempty today modifiers ts}  -- PARTIAL:+  let j' = j{jtxns=either error' id $ modifyTransactions (journalAccountType j) (journalInheritedAccountTags j) mempty today modifiers ts}  -- PARTIAL:   -- run the print command, showing all transactions, or show diffs   printOrDiff rawopts opts{reportspec_=rspec{_rsQuery=Any}} j j' 

@@ -66,7 +66,7 @@     styles = journalCommodityStyles j     mixedAmountValue periodlast date =         maybe id (mixedAmountApplyValuation priceOracle styles periodlast today date) value_-        . mixedAmountToCost cost_ styles+      . maybe id (mixedAmountToCost styles) conversionop_    let     ropts = _rsReportOpts rspec@@ -81,25 +81,14 @@   pnlQuery         <- makeQuery "pnl"    let-    trans = dbg3 "investments" $ jtxns $ filterJournalTransactions investmentsQuery j--    journalSpan =-        let dates = map (transactionDateOrDate2 wd) trans in-        DateSpan (Just $ minimum dates) (Just $ addDays 1 $ maximum dates)--    requestedSpan = periodAsDateSpan period_-    requestedInterval = interval_--    wholeSpan = dbg3 "wholeSpan" $ spanDefaultsFrom requestedSpan journalSpan+    filteredj = filterJournalTransactions investmentsQuery j+    trans = dbg3 "investments" $ jtxns filteredj    when (null trans) $ do     putStrLn "No relevant transactions found. Check your investments query"     exitFailure -  let spans = case requestedInterval of-        NoInterval -> [wholeSpan]-        interval ->-            splitSpan interval wholeSpan+  let spans = snd $ reportSpan filteredj rspec    let priceDirectiveDates = dbg3 "priceDirectiveDates" $ map pddate $ jpricedirectives j @@ -176,7 +165,7 @@         -- one for the given date, by construction.         zeroUnitsNeedsCashflowAtTheFront         $ sort-        $ dailyCashflows ++ datedPnls+        $ datedCashflows ++ datedPnls         where           zeroUnitsNeedsCashflowAtTheFront changes =             if initialUnits > 0 then changes@@ -185,16 +174,18 @@                   (firstCashflow, rest') = splitAt 1 rest               in firstCashflow ++ leadingPnls ++ rest' -          datedPnls = map (\(date,amt) -> (date,Left $ maNegate amt)) pnl+          datedPnls = map (second Left) $ aggregateByDate pnl  -          dailyCashflows =+          datedCashflows = map (second Right) $ aggregateByDate cashFlow++          aggregateByDate datedAmounts = +            -- Aggregate all entries for a single day, assuming that intraday interest is negligible             sort-          -- Aggregate all entries for a single day, assuming that intraday interest is negligible-            $ map (\date_cash -> let (dates, cash) = unzip date_cash in (head dates, Right (maSum cash)))+            $ map (\date_cash -> let (dates, cash) = unzip date_cash in (head dates, maSum cash))             $ groupBy ((==) `on` fst)             $ sortOn fst             $ map (second maNegate)-            $ cashFlow+            $ datedAmounts    let units =         tail $@@ -216,7 +207,9 @@           $ dbg3 "changes" changes    let finalUnitBalance = if null units then initialUnits else let (_,_,_,u) = last units in u-      finalUnitPrice = if finalUnitBalance == 0 then initialUnitPrice+      finalUnitPrice = if finalUnitBalance == 0 then+                         if null units then initialUnitPrice+                         else let (_,_,lastUnitPrice,_) = last units in lastUnitPrice                        else (unMix valueAfter) / finalUnitBalance       -- Technically, totalTWR should be (100*(finalUnitPrice - initialUnitPrice) / initialUnitPrice), but initalUnitPrice is 100, so 100/100 == 1       totalTWR = roundTo 2 $ (finalUnitPrice - initialUnitPrice)

@@ -33,9 +33,9 @@ Examples:  -   Using roi to compute total return of investment in stocks:-    https://github.com/simonmichael/hledger/blob/master/examples/roi-unrealised.ledger+    https://github.com/simonmichael/hledger/blob/master/examples/investing/roi-unrealised.ledger --   Cookbook -> Return on Investment+-   Cookbook > Return on Investment: https://hledger.org/roi.html  Spaces and special characters in --inv and --pnl @@ -155,6 +155,10 @@ in "unit price" over the reporting period gives you rate of return of your investment. -References: * Explanation of rate of return * Explanation of IRR *-Explanation of TWR * Examples of computing IRR and TWR and discussion of-the limitations of both metrics+References:++-   Explanation of rate of return+-   Explanation of IRR+-   Explanation of TWR+-   Examples of computing IRR and TWR and discussion of the limitations+    of both metrics

@@ -48,8 +48,7 @@   let today = _rsDay rspec       q = _rsQuery rspec       l = ledgerFromJournal q j-      reportspan = ledgerDateSpan l `spanDefaultsFrom` queryDateSpan False q-      intervalspans = splitSpan (interval_ $ _rsReportOpts rspec) reportspan+      intervalspans = snd $ reportSpanBothDates j rspec       showstats = showLedgerStats l today       (ls, txncounts) = unzip $ map showstats intervalspans       numtxns = sum txncounts

@@ -136,7 +136,7 @@             _          -> showDateSpan requestedspan           where             enddates = map (addDays (-1)) . mapMaybe spanEnd $ cbrDates cbr  -- these spans will always have a definite end date-            requestedspan = reportSpan j rspec+            requestedspan = fst $ reportSpan j rspec          -- when user overrides, add an indication to the report title         -- Do we need to deal with overridden BalanceCalculation?@@ -152,9 +152,9 @@             _                                              -> Nothing          valuationdesc =-          (case cost_ of-               Cost   -> ", converted to cost"-               NoCost -> "")+          (case conversionop_ of+               Just ToCost -> ", converted to cost"+               _           -> "")           <> (case value_ of                Just (AtThen _mc)       -> ", valued at posting date"                Just (AtEnd _mc) | changingValuation -> ""

@@ -1,5 +1,5 @@ -.TH "HLEDGER-UI" "1" "December 2021" "hledger-ui-1.24.99 " "hledger User Manuals"+.TH "HLEDGER-UI" "1" "March 2022" "hledger-ui-1.25 " "hledger User Manuals"   @@ -7,7 +7,7 @@ .PP hledger-ui is a terminal interface (TUI) for the hledger accounting tool.-This manual is for hledger-ui 1.24.99.+This manual is for hledger-ui 1.25. .SH SYNOPSIS .PP \f[C]hledger-ui [OPTIONS] [QUERYARGS]\f[R]

@@ -12,7 +12,7 @@ *************  hledger-ui is a terminal interface (TUI) for the hledger accounting-tool.  This manual is for hledger-ui 1.24.99.+tool.  This manual is for hledger-ui 1.25.     'hledger-ui [OPTIONS] [QUERYARGS]' 'hledger ui -- [OPTIONS] [QUERYARGS]'@@ -639,34 +639,34 @@  Tag Table: Node: Top221-Node: OPTIONS1657-Ref: #options1755-Node: MOUSE6637-Ref: #mouse6732-Node: KEYS7014-Ref: #keys7107-Node: SCREENS11193-Ref: #screens11291-Node: Accounts screen11381-Ref: #accounts-screen11509-Node: Register screen13848-Ref: #register-screen14003-Node: Transaction screen15987-Ref: #transaction-screen16145-Node: Error screen17015-Ref: #error-screen17137-Node: TIPS17381-Ref: #tips17480-Node: Watch mode17532-Ref: #watch-mode17649-Node: Watch mode limitations18399-Ref: #watch-mode-limitations18540-Node: ENVIRONMENT19676-Ref: #environment19787-Node: FILES21095-Ref: #files21194-Node: BUGS21407-Ref: #bugs21484+Node: OPTIONS1654+Ref: #options1752+Node: MOUSE6634+Ref: #mouse6729+Node: KEYS7011+Ref: #keys7104+Node: SCREENS11190+Ref: #screens11288+Node: Accounts screen11378+Ref: #accounts-screen11506+Node: Register screen13845+Ref: #register-screen14000+Node: Transaction screen15984+Ref: #transaction-screen16142+Node: Error screen17012+Ref: #error-screen17134+Node: TIPS17378+Ref: #tips17477+Node: Watch mode17529+Ref: #watch-mode17646+Node: Watch mode limitations18396+Ref: #watch-mode-limitations18537+Node: ENVIRONMENT19673+Ref: #environment19784+Node: FILES21092+Ref: #files21191+Node: BUGS21404+Ref: #bugs21481  End Tag Table 

@@ -5,7 +5,7 @@  NAME        hledger-ui  is  a  terminal  interface (TUI) for the hledger accounting-       tool.  This manual is for hledger-ui 1.24.99.+       tool.  This manual is for hledger-ui 1.25.  SYNOPSIS        hledger-ui [OPTIONS] [QUERYARGS]@@ -548,4 +548,4 @@   -hledger-ui-1.24.99               December 2021                   HLEDGER-UI(1)+hledger-ui-1.25                   March 2022                     HLEDGER-UI(1)

@@ -1,12 +1,12 @@ -.TH "HLEDGER-WEB" "1" "December 2021" "hledger-web-1.24.99 " "hledger User Manuals"+.TH "HLEDGER-WEB" "1" "March 2022" "hledger-web-1.25 " "hledger User Manuals"    .SH NAME .PP hledger-web is a web interface (WUI) for the hledger accounting tool.-This manual is for hledger-web 1.24.99.+This manual is for hledger-web 1.25. .SH SYNOPSIS .PP \f[C]hledger-web [OPTIONS]\f[R]

@@ -12,7 +12,7 @@ **************  hledger-web is a web interface (WUI) for the hledger accounting tool.-This manual is for hledger-web 1.24.99.+This manual is for hledger-web 1.25.     'hledger-web [OPTIONS]' 'hledger web -- [OPTIONS]'@@ -631,22 +631,22 @@  Tag Table: Node: Top223-Node: OPTIONS1889-Ref: #options1994-Node: PERMISSIONS9905-Ref: #permissions10044-Node: EDITING UPLOADING DOWNLOADING11256-Ref: #editing-uploading-downloading11437-Node: RELOADING12271-Ref: #reloading12405-Node: JSON API12838-Ref: #json-api12952-Node: ENVIRONMENT18442-Ref: #environment18558-Node: FILES19792-Ref: #files19892-Node: BUGS20105-Ref: #bugs20183+Node: OPTIONS1886+Ref: #options1991+Node: PERMISSIONS9902+Ref: #permissions10041+Node: EDITING UPLOADING DOWNLOADING11253+Ref: #editing-uploading-downloading11434+Node: RELOADING12268+Ref: #reloading12402+Node: JSON API12835+Ref: #json-api12949+Node: ENVIRONMENT18439+Ref: #environment18555+Node: FILES19789+Ref: #files19889+Node: BUGS20102+Ref: #bugs20180  End Tag Table 

@@ -5,7 +5,7 @@  NAME        hledger-web  is  a web interface (WUI) for the hledger accounting tool.-       This manual is for hledger-web 1.24.99.+       This manual is for hledger-web 1.25.  SYNOPSIS        hledger-web [OPTIONS]@@ -585,4 +585,4 @@   -hledger-web-1.24.99              December 2021                  HLEDGER-WEB(1)+hledger-web-1.25                  March 2022                    HLEDGER-WEB(1)

@@ -1,6 +1,6 @@ .\"t -.TH "HLEDGER" "1" "December 2021" "hledger-1.24.99 " "hledger User Manuals"+.TH "HLEDGER" "1" "March 2022" "hledger-1.25 " "hledger User Manuals"   @@ -9,7 +9,7 @@ This is the command-line interface (CLI) for the hledger accounting tool. Here we also describe hledger\[aq]s concepts and file formats.-This manual is for hledger 1.24.99.+This manual is for hledger 1.25. .SH SYNOPSIS .PP \f[C]hledger\f[R]@@ -706,8 +706,8 @@ .IP \[bu] 2 Are all commodity conversions declared explicitly ? .PP-You can also use the check command to run these and some additional-checks.+You can use the check command to run individual checks -- the ones+listed above and some more. .SH TIME PERIODS .SS Smart dates .PP@@ -764,6 +764,21 @@ -1, 0, 1 periods from the current period T} T{+\f[C]in n days/weeks/months/quarters/years\f[R]+T}@T{+n periods from the current period+T}+T{+\f[C]n days/weeks/months/quarters/years ahead\f[R]+T}@T{+n periods from the current period+T}+T{+\f[C]n days/weeks/months/quarters/years ago\f[R]+T}@T{+-n periods from the current period+T}+T{ \f[C]20181201\f[R] T}@T{ 8 digit YYYYMMDD with valid year month and day@@ -1449,15 +1464,33 @@ .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[C]TYPECODES\f[R] is one or more of the single-letter account type+codes \f[C]ALERXCV\f[R], case insensitive.+Note \f[C]type:A\f[R] and \f[C]type:E\f[R] will also match their+respective subtypes \f[C]C\f[R] (Cash) and \f[C]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[C]tag:.=REGEX\f[R].) Note that postings-also inherit tags from their transaction, and transactions also acquire-tags from their postings, when querying.+(To match only by value, use \f[C]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@@ -1529,12 +1562,198 @@ the old one. Note: this changed in hledger 1.22, previously it was the reverse, see the discussion at #1625.-.SH COSTING+.SH CONVERSION & COST .PP-The \f[C]-B/--cost\f[R] flag converts amounts to their cost or sale-amount at transaction time, if they have a transaction price specified.-If this flag is supplied, hledger will perform cost conversion first,-and will apply any market price valuations (if requested) afterwards.+This section is about converting between commodities.+Some definitions:+.IP \[bu] 2+A \[dq]commodity conversion\[dq] is an exchange of one currency or+commodity for another.+Eg a foreign currency exchange, or a purchase or sale of stock or+cryptocurrency.+.IP \[bu] 2+A \[dq]conversion transaction\[dq] is a transaction involving one or+more such conversions.+.IP \[bu] 2+\[dq]Conversion rate\[dq] is the exchange rate in a conversion - the+cost per unit of one commodity in the other.+.IP \[bu] 2+\[dq]Cost\[dq] is how much of one commodity was paid to acquire the+other (when buying), or how much was received in exchange for the other+(when selling).+We call both of these \[dq]cost\[dq] for convenience (after all, it is+cost for one party or the other).+.SS Recording conversions+.PP+As a concrete example, let\[aq]s assume 100 EUR was converted to 120+USD.+There are several ways to record this in the journal, each with pros and+cons which will be explained in more detail below.+(Also, these examples use journal format which is properly explained+much further below; sorry about that, you may want to read some of that+first.)+.SS Implicit conversion+.PP+You can just record the outflow (100 EUR) and inflow (120 USD) in the+appropriate asset account:+.IP+.nf+\f[C]+2021-01-01+    assets:cash    -100 EUR+    assets:cash     120 USD+\f[R]+.fi+.PP+hledger will assume this transaction is balanced, inferring that the+conversion rate must be 1 EUR = 1.20 USD.+You can see the inferred rate by using \f[C]hledger print -x\f[R].+.PP+Pro:+.IP \[bu] 2+Easy, concise+.IP \[bu] 2+hledger can do cost reporting+.PP+Con:+.IP \[bu] 2+Less error checking - typos in amounts or commodity symbols may not be+detected+.IP \[bu] 2+conversion rate is not clear+.IP \[bu] 2+disturbs the accounting equation+.PP+You can prevent accidental implicit conversions due to a mistyped+commodity symbol, by using \f[C]hledger check commodities\f[R].+You can prevent implicit conversions entirely, by using+\f[C]hledger check balancednoautoconversion\f[R], or+\f[C]-s/--strict\f[R].+.SS Priced conversion+.PP+You can add the conversion rate using \[at] notation:+.IP+.nf+\f[C]+2021-01-01+    assets:cash        -100 EUR \[at] 1.20 USD+    assets:cash         120 USD+\f[R]+.fi+.PP+Now hledger will check that 100 * 1.20 = 120, and would report an error+otherwise.+.PP+Pro:+.IP \[bu] 2+Still concise+.IP \[bu] 2+makes the conversion rate clear+.IP \[bu] 2+provides some error checking+.IP \[bu] 2+hledger can do cost reporting+.PP+Con:+.IP \[bu] 2+Disturbs the accounting equation+.SS Equity conversion+.PP+In strict double entry bookkeeping, the above transaction is not+balanced in EUR or in USD, since some EUR disappears, and some USD+appears.+This violates the accounting equation (A+L+E=0), and prevents reports+like \f[C]balancesheetequity\f[R] from showing a zero total.+.PP+The proper way to make it balance is to add a balancing posting for each+commodity, using an equity account:+.IP+.nf+\f[C]+2021-01-01+    assets:cash        -100 EUR+    equity:conversion   100 EUR+    equity:conversion  -120 USD+    assets:cash         120 USD+\f[R]+.fi+.PP+Pro:+.IP \[bu] 2+Preserves the accounting equation+.IP \[bu] 2+keeps track of conversions and related gains/losses in one place+.IP \[bu] 2+works in any double entry accounting system+.PP+Con:+.IP \[bu] 2+More verbose+.IP \[bu] 2+conversion rate is not clear+.IP \[bu] 2+hledger can not do cost reporting+.SS Priced equity conversion+.PP+Another possible notation would be to record both the conversion rate+and the equity postings:+.IP+.nf+\f[C]+2021-01-01+    assets:cash        -100 EUR \[at] 1.20 USD+    equity:conversion   100 EUR+    equity:conversion  -120 USD+    assets:cash         120 USD+\f[R]+.fi+.PP+hledger currently does not allow this; instead, you can record the+conversion rate as a comment.+.SS Inferring missing conversion rates+.PP+hledger will do this automatically for implicit conversions.+Currently it can not do this for equity conversions.+.SS Inferring missing equity postings+.PP+With the \f[C]--infer-equity\f[R] flag, hledger will add equity postings+to priced and implicit conversions (and move the conversion rate into a+comment).+.SS Cost reporting+.PP+With the \f[C]-B/--cost\f[R] flag, hledger will convert the amounts in+priced and implicit conversions to their cost in the other commodity.+This is useful to see a report of what you paid for things (or how much+you sold things for).+Currently \f[C]-B/--cost\f[R] does not work on equity conversions, and+it disables \f[C]--infer-equity\f[R].+.PP+These operations are transient, only affecting reports.+If you want to change the journal file permanently, you could pipe each+entry through \f[C]hledger -f- -I print [-x] [--infer-equity] [-B]\f[R]+.SS Conversion summary+.IP \[bu] 2+Recording the conversion rate is good because it makes that clear and+allows cost reporting.+.IP \[bu] 2+Recording equity postings is good because it balances the accounting+equation and is correct bookkeeping.+.IP \[bu] 2+Combining these is not yet supported, so you have to choose.+For now, priced conversions are a good compromise, so that:+.RS 2+.IP \[bu] 2+When you want to see the cost (or sale proceeds) of things, use+\f[C]-B/--cost\f[R].+.IP \[bu] 2+When you want to see a balanced balance sheet or correct journal+entries, use \f[C]--infer-equity\f[R].+.IP \[bu] 2+Combining these is not yet supported; \f[C]-B/--cost\f[R] will take+precedence.+.RE+.IP \[bu] 2+Conversion/cost operations are performed before valuation. .SH VALUATION .PP Instead of reporting amounts in their original commodity, hledger can@@ -2733,6 +2952,10 @@ Account names can be depth-clipped with \f[C]depth:N\f[R] or \f[C]--depth N\f[R] or \f[C]-N\f[R]. .PP+With \f[C]--types\f[R], it also shows each account\[aq]s type, if+it\[aq]s known.+(See Declaring accounts > Account types.)+.PP Examples: .IP .nf@@ -5171,6 +5394,8 @@ 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. .PP Normally, the journal entry\[aq]s explicit or implicit amount style is preserved.@@ -5652,9 +5877,9 @@ Examples: .IP \[bu] 2 Using roi to compute total return of investment in stocks:-https://github.com/simonmichael/hledger/blob/master/examples/roi-unrealised.ledger+https://github.com/simonmichael/hledger/blob/master/examples/investing/roi-unrealised.ledger .IP \[bu] 2-Cookbook -> Return on Investment+Cookbook > Return on Investment: https://hledger.org/roi.html .SS Spaces and special characters in \f[C]--inv\f[R] and \f[C]--pnl\f[R] .PP Note that \f[C]--inv\f[R] and \f[C]--pnl\f[R]\[aq]s argument is a query,@@ -5805,9 +6030,16 @@ Change in \[dq]unit price\[dq] over the reporting period gives you rate of return of your investment. .PP-References: * Explanation of rate of return * Explanation of IRR *-Explanation of TWR * Examples of computing IRR and TWR and discussion of-the limitations of both metrics+References:+.IP \[bu] 2+Explanation of rate of return+.IP \[bu] 2+Explanation of IRR+.IP \[bu] 2+Explanation of TWR+.IP \[bu] 2+Examples of computing IRR and TWR and discussion of the limitations of+both metrics .SS stats .PP stats@@ -7399,6 +7631,12 @@ been declared by a \f[C]commodity\f[R] directive. This works similarly to account error checking, see the notes there for more details.+.PP+Note, this disallows amounts without a commodity symbol, because+currently it\[aq]s not possible (?) to declare the \[dq]no-symbol\[dq]+commodity with a directive.+This is one exception for convenience: zero amounts are always allowed+to have no commodity symbol. .SS Default commodity .PP The \f[C]D\f[R] directive sets a default commodity, to be used for any@@ -7479,18 +7717,18 @@ They can document your intended chart of accounts, providing a reference. .IP \[bu] 2+They control 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), useful for reports like balancesheet and incomestatement. .IP \[bu] 2-They control account display order in reports, allowing non-alphabetic-sorting (eg Revenues to appear above Expenses).-.IP \[bu] 2-They can store extra information about accounts (account numbers, notes,-etc.)+They can store other account information, as comments or as tags which+can be used to filter reports. .IP \[bu] 2-They help with account name completion in the add command, hledger-iadd,-hledger-web, ledger-mode etc.+They help with account name completion (in hledger add, hledger-web,+hledger-iadd, ledger-mode, etc.) .IP \[bu] 2 In strict mode, they restrict which accounts may be posted to by transactions, which helps detect typos.@@ -7547,13 +7785,14 @@ .IP .nf \f[C]-account assets:bank:checking  ; same-line comment, note 2+ spaces before ;+account assets:bank:checking    ; same-line comment, note 2+ spaces required before ;   ; next-line comment-  ; another with tag, acctno:12345 (not used yet)+  ; some tags, type:A, acctnum:12345 \f[R] .fi .PP-Same-line comments are not supported by Ledger, or hledger <1.13.+Compatibility note: same-line comments are not supported by Ledger or+hledger <1.13. .SS Account subdirectives .PP We also allow (and ignore) Ledger-style indented subdirectives, just for@@ -7570,85 +7809,124 @@ .IP .nf \f[C]-account ACCTNAME  [ACCTTYPE] [;COMMENT]+account ACCTNAME  [;type:ACCTTYPE] [COMMENT]   [;COMMENTS]   [LEDGER-STYLE SUBDIRECTIVES, IGNORED] \f[R] .fi .SS Account types .PP-By adding a \f[C]type\f[R] tag to the account directive, with value-\f[C]A\f[R], \f[C]L\f[R], \f[C]E\f[R], \f[C]R\f[R], \f[C]X\f[R],-\f[C]C\f[R] (or if you prefer: \f[C]Asset\f[R], \f[C]Liability\f[R],-\f[C]Equity\f[R], \f[C]Revenue\f[R], \f[C]Expense\f[R], \f[C]Cash\f[R]),-you can declare hledger accounts to be of a certain type:+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[C]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 generally we recommend you declare types explicitly, by adding a+\f[C]type:\f[R] tag to your top-level account directives.+Subaccounts will inherit the type of their parent.+The tag\[aq]s value should be one of the five main account types: .IP \[bu] 2-\f[B]asset\f[R], \f[B]liability\f[R], \f[B]equity\f[R],-\f[B]revenue\f[R], \f[B]expense\f[R]-.PD 0-.P-.PD-the standard types in accounting, or+\f[C]A\f[R] or \f[C]Asset\f[R] (things you own) .IP \[bu] 2-\f[B]cash\f[R]-.PD 0-.P-.PD-a subtype of asset, used for liquid assets.+\f[C]L\f[R] or \f[C]Liability\f[R] (things you owe)+.IP \[bu] 2+\f[C]E\f[R] or \f[C]Equity\f[R] (investment/ownership; balanced+counterpart of assets & liabilities)+.IP \[bu] 2+\f[C]R\f[R] or \f[C]Revenue\f[R] (what you received money from, AKA+income; technically part of Equity)+.IP \[bu] 2+\f[C]X\f[R] or \f[C]Expense\f[R] (what you spend money on; technically+part of Equity) .PP-Declaring account types is a good idea, since it helps enable the easy-balancesheet, balancesheetequity, incomestatement and cashflow reports,-and probably other things in future.-As a convenience, when account types are not declared, hledger will try-to guess them based on english-language account names.+or, it can be (these are used less often):+.IP \[bu] 2+\f[C]C\f[R] or \f[C]Cash\f[R] (a subtype of Asset, indicating liquid+assets for the cashflow report)+.IP \[bu] 2+\f[C]V\f[R] or \f[C]Conversion\f[R] (a subtype of Equity, for+conversions (see CONVERSION & COST).) .PP-Here is a typical set of top-level account declarations (because of the-aforementioned, with these account names the type tags are not strictly-needed, but with non-english or non-standard account names, they will-be):+Here is a typical set of account type declarations: .IP .nf \f[C]-account assets       ; type: A-account liabilities  ; type: L-account equity       ; type: E-account revenues     ; type: R-account expenses     ; type: X+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 assets:bank        ; type: C+account assets:cash        ; type: C++account equity:conversion  ; type: V \f[R] .fi .PP-It\[aq]s not necessary to declare the type of subaccounts.-(You can, if they are different from the parent, but this is not-common.)-.SS Auto-detected account types-.PP-More about \[dq]guessing\[dq] account types: hledger tries to find at-least one top level account in each of the six account types (Asset,-Liability, Equity, Revenue, Expense, Cash).-When no accounts have been declared for a particular type, it tries to-auto-detect some accounts by name, using the regular expressions below.-Note: if you declare any account\[aq]s type, it\[aq]s a good idea to-declare an account for all six types, because a mix of declared and-auto-detected types can cause confusing results.-.PP-The auto-detection rules are:+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.+Note the Cash regexp changed in hledger 1.24.99.2.+.RS 2 .IP .nf \f[C]- If account\[aq]s name matches this case insensitive regular expression:| its type is:-------------------------------------------------------------------- | ------------- \[ha]assets?(:|$)                                                      | -   and does not contain regexp (investment|receivable|:A/R|:fixed)  | Cash-   otherwise                                                        | Asset- \[ha](debts?|liabilit(y|ies))(:|$)                                     | Liability- \[ha]equity(:|$)                                                       | Equity- \[ha](income|revenue)s?(:|$)                                           | Revenue- \[ha]expenses?(:|$)                                                    | Expense+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 \f[R] .fi+.RE+.IP \[bu] 2+If you declare any account types, it\[aq]s a good idea to declare an+account for each of them, because a mixture of declared and+name-inferred types can disrupt certain reports.+.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.+To be precise, an account\[aq]s type is decided by the first of these+that exists:+.RS 2+.IP "1." 3+A \f[C]type:\f[R] declaration for this account.+.IP "2." 3+A \f[C]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+.nf+\f[C]+$ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES]+\f[R]+.fi+.RE .SS Account display order .PP Account directives also set the order in which accounts are displayed,@@ -7715,15 +7993,21 @@ .IP \[bu] 2 adapting old journals to your current chart of accounts .IP \[bu] 2-experimenting with new account organisations, like a new hierarchy or-combining two accounts into one+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 .PP@@ -7868,6 +8152,70 @@ end aliases \f[R] .fi+.SS Aliases can generate bad account names+.PP+Be aware that account aliases can produce malformed account names, which+could cause confusing reports or invalid \f[C]print\f[R] output.+For example, you could erase all account names:+.IP+.nf+\f[C]+2021-01-01+  a:aa     1+  b+\f[R]+.fi+.IP+.nf+\f[C]+$ hledger print --alias \[aq]/.*/=\[aq]+2021-01-01+                   1+\f[R]+.fi+.PP+The above \f[C]print\f[R] output is not a valid journal.+Or you could insert an illegal double space, causing \f[C]print\f[R]+output that would give a different journal when reparsed:+.IP+.nf+\f[C]+2021-01-01+  old    1+  other+\f[R]+.fi+.IP+.nf+\f[C]+$ hledger print --alias old=\[dq]new  USD\[dq] | hledger -f- print+2021-01-01+    new             USD 1+    other+\f[R]+.fi+.SS Aliases and account types+.PP+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[C]type:\f[R] query is not+matching accounts as you expect, try troubleshooting with the accounts+command, eg something like:+.IP+.nf+\f[C]+$ hledger accounts --alias assets=bassetts type:a+\f[R]+.fi .SS Default parent account .PP You can specify a parent account which will be prepended to all accounts@@ -9459,14 +9807,14 @@ .fi .RE .IP "3." 3-\f[B]If you are stuck with hledger <1.17, or you want posting 2\[aq]s-amount converted to cost:\f[R]+\f[B]If you want posting 2\[aq]s amount converted to cost:\f[R] .PD 0 .P .PD Assign to \f[C]amount\f[R] (or to \f[C]amount-in\f[R] and \f[C]amount-out\f[R]).-(The old numberless syntax, which sets amount1 and amount2.)+(This is the legacy numberless syntax, which sets amount1 and amount2+and converts amount2 to cost.) .IP "4." 3 \f[B]If the CSV has the balance instead of the transaction amount:\f[R] .PD 0@@ -10005,7 +10353,7 @@ .fi .PP Find more docs, chat, mail list, reddit, issue tracker:-https://hledger.org#help-feedback+https://hledger.org/support.html-feedback .SS Constructing command lines .PP hledger has an extensive and powerful command line interface.

@@ -13,9622 +13,9961 @@  This is the command-line interface (CLI) for the hledger accounting tool.  Here we also describe hledger's concepts and file formats.  This-manual is for hledger 1.24.99.--   'hledger'--   'hledger [-f FILE] COMMAND [OPTIONS] [ARGS]'--   'hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS]'--   hledger is a reliable, cross-platform set of programs for tracking-money, time, or any other commodity, using double-entry accounting and a-simple, editable file format.  hledger is inspired by and largely-compatible with ledger(1).--   The basic function of the hledger CLI is to read a plain text file-describing financial transactions (in accounting terms, a general-journal) and print useful reports on standard output, or export them as-CSV. hledger can also read some other file formats such as CSV files,-translating them to journal format.  Additionally, hledger lists other-hledger-* executables found in the user's $PATH and can invoke them as-subcommands.--   hledger reads data from one or more files in hledger journal,-timeclock, timedot, or CSV format specified with '-f', or-'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps-'C:/Users/USER/.hledger.journal').  If using '$LEDGER_FILE', note this-must be a real environment variable, not a shell variable.  You can-specify standard input with '-f-'.--   Transactions are dated movements of money between two (or more) named-accounts, and are recorded with journal entries like this:--2015/10/16 bought food- expenses:food          $10- assets:cash--   Most users use a text editor to edit the journal, usually with an-editor mode such as ledger-mode for added convenience.  hledger's-interactive add command is another way to record new transactions.-hledger never changes existing transactions.--   To get started, you can either save some entries like the above in-'~/.hledger.journal', or run 'hledger add' and follow the prompts.  Then-try some commands like 'hledger print' or 'hledger balance'.  Run-'hledger' with no arguments for a list of commands.--* Menu:--* OPTIONS::-* ENVIRONMENT::-* DATA FILES::-* TIME PERIODS::-* DEPTH::-* QUERIES::-* COSTING::-* VALUATION::-* PIVOTING::-* OUTPUT::-* COMMANDS::-* JOURNAL FORMAT::-* CSV FORMAT::-* TIMECLOCK FORMAT::-* TIMEDOT FORMAT::-* COMMON TASKS::-* LIMITATIONS::-* TROUBLESHOOTING::---File: hledger.info,  Node: OPTIONS,  Next: ENVIRONMENT,  Prev: Top,  Up: Top--1 OPTIONS-*********--* Menu:--* General options::-* Command options::-* Command arguments::-* Special characters::-* Unicode characters::-* Regular expressions::---File: hledger.info,  Node: General options,  Next: Command options,  Up: OPTIONS--1.1 General options-===================--To see general usage help, including general options which are supported-by most hledger commands, run 'hledger -h'.--   General help options:--'-h --help'--     show general or COMMAND help-'--man'--     show general or COMMAND user manual with man-'--info'--     show general or COMMAND user manual with info-'--version'--     show general or ADDONCMD version-'--debug[=N]'--     show debug output (levels 1-9, default: 1)--   General input options:--'-f FILE --file=FILE'--     use a different input file.  For stdin, use - (default:-     '$LEDGER_FILE' or '$HOME/.hledger.journal')-'--rules-file=RULESFILE'--     Conversion rules file to use when reading CSV (default: FILE.rules)-'--separator=CHAR'--     Field separator to expect when reading CSV (default: ',')-'--alias=OLD=NEW'--     rename accounts named OLD to NEW-'--anon'--     anonymize accounts and payees-'--pivot FIELDNAME'--     use some other field or tag for the account name-'-I --ignore-assertions'--     disable balance assertion checks (note: does not disable balance-     assignments)-'-s --strict'--     do extra error checking (check that all posted accounts are-     declared)--   General reporting options:--'-b --begin=DATE'--     include postings/txns on or after this date (will be adjusted to-     preceding subperiod start when using a report interval)-'-e --end=DATE'--     include postings/txns before this date (will be adjusted to-     following subperiod end when using a report interval)-'-D --daily'--     multiperiod/multicolumn report by day-'-W --weekly'--     multiperiod/multicolumn report by week-'-M --monthly'--     multiperiod/multicolumn report by month-'-Q --quarterly'--     multiperiod/multicolumn report by quarter-'-Y --yearly'--     multiperiod/multicolumn report by year-'-p --period=PERIODEXP'--     set start date, end date, and/or reporting interval all at once-     using period expressions syntax-'--date2'--     match the secondary date instead (see command help for other-     effects)-'--today=DATE'--     override today's date (affects relative smart dates, for-     tests/examples)-'-U --unmarked'--     include only unmarked postings/txns (can combine with -P or -C)-'-P --pending'--     include only pending postings/txns-'-C --cleared'--     include only cleared postings/txns-'-R --real'--     include only non-virtual postings-'-NUM --depth=NUM'--     hide/aggregate accounts or postings more than NUM levels deep-'-E --empty'--     show items with zero amount, normally hidden (and vice-versa in-     hledger-ui/hledger-web)-'-B --cost'--     convert amounts to their cost/selling amount at transaction time-'-V --market'--     convert amounts to their market value in default valuation-     commodities-'-X --exchange=COMM'--     convert amounts to their market value in commodity COMM-'--value'--     convert amounts to cost or market value, more flexibly than-     -B/-V/-X-'--infer-market-prices'--     use transaction prices (recorded with @ or @@) as additional market-     prices, as if they were P directives-'--auto'--     apply automated posting rules to modify transactions.-'--forecast'--     generate future transactions from periodic transaction rules, for-     the next 6 months or till report end date.  In hledger-ui, also-     make ordinary future transactions visible.-'--commodity-style'--     Override the commodity style in the output for the specified-     commodity.  For example 'EUR1.000,00'.-'--color=WHEN (or --colour=WHEN)'--     Should color-supporting commands use ANSI color codes in text-     output.  'auto' (default): whenever stdout seems to be a-     color-supporting terminal.  'always' or 'yes': always, useful eg-     when piping output into 'less -R'. 'never' or 'no': never.  A-     NO_COLOR environment variable overrides this.-'--pretty[=WHEN]'--     Show prettier output, e.g.  using unicode box-drawing characters.-     Accepts 'yes' (the default) or 'no' ('y', 'n', 'always', 'never'-     also work).  If you provide an argument you must use '=', e.g.-     '-pretty=yes'.--   When a reporting option appears more than once in the command line,-the last one takes precedence.--   Some reporting options can also be written as query arguments.---File: hledger.info,  Node: Command options,  Next: Command arguments,  Prev: General options,  Up: OPTIONS--1.2 Command options-===================--To see options for a particular command, including command-specific-options, run: 'hledger COMMAND -h'.--   Command-specific options must be written after the command name, eg:-'hledger print -x'.--   Additionally, if the command is an add-on, you may need to put its-options after a double-hyphen, eg: 'hledger ui -- --watch'.  Or, you can-run the add-on executable directly: 'hledger-ui --watch'.---File: hledger.info,  Node: Command arguments,  Next: Special characters,  Prev: Command options,  Up: OPTIONS--1.3 Command arguments-=====================--Most hledger commands accept arguments after the command name, which are-often a query, filtering the data in some way.--   You can save a set of command line options/arguments in a file, and-then reuse them by writing '@FILENAME' as a command line argument.  Eg:-'hledger bal @foo.args'.  (To prevent this, eg if you have an argument-that begins with a literal '@', precede it with '--', eg: 'hledger bal--- @ARG').--   Inside the argument file, each line should contain just one option or-argument.  Avoid the use of spaces, except inside quotes (or you'll see-a confusing error).  Between a flag and its argument, use = (or-nothing).  Bad:--assets depth:2--X USD--   Good:--assets-depth:2--X=USD--   For special characters (see below), use one less level of quoting-than you would at the command prompt.  Bad:---X"$"--   Good:---X$--   See also: Save frequently used options.---File: hledger.info,  Node: Special characters,  Next: Unicode characters,  Prev: Command arguments,  Up: OPTIONS--1.4 Special characters-======================--* Menu:--* Single escaping shell metacharacters::-* Double escaping regular expression metacharacters::-* Triple escaping for add-on commands::-* Less escaping::---File: hledger.info,  Node: Single escaping shell metacharacters,  Next: Double escaping regular expression metacharacters,  Up: Special characters--1.4.1 Single escaping (shell metacharacters)-----------------------------------------------In shell command lines, characters significant to your shell - such as-spaces, '<', '>', '(', ')', '|', '$' and '\' - should be "shell-escaped"-if you want hledger to see them.  This is done by enclosing them in-single or double quotes, or by writing a backslash before them.  Eg to-match an account name containing a space:--$ hledger register 'credit card'--   or:--$ hledger register credit\ card--   Windows users should keep in mind that 'cmd' treats single quote as a-regular character, so you should be using double quotes exclusively.-PowerShell treats both single and double quotes as quotes.---File: hledger.info,  Node: Double escaping regular expression metacharacters,  Next: Triple escaping for add-on commands,  Prev: Single escaping shell metacharacters,  Up: Special characters--1.4.2 Double escaping (regular expression metacharacters)------------------------------------------------------------Characters significant in regular expressions (described below) - such-as '.', '^', '$', '[', ']', '(', ')', '|', and '\' - may need to be-"regex-escaped" if you don't want them to be interpreted by hledger's-regular expression engine.  This is done by writing backslashes before-them, but since backslash is typically also a shell metacharacter, both-shell-escaping and regex-escaping will be needed.  Eg to match a literal-'$' sign while using the bash shell:--$ hledger balance cur:'\$'--   or:--$ hledger balance cur:\\$---File: hledger.info,  Node: Triple escaping for add-on commands,  Next: Less escaping,  Prev: Double escaping regular expression metacharacters,  Up: Special characters--1.4.3 Triple escaping (for add-on commands)----------------------------------------------When you use hledger to run an external add-on command (described-below), one level of shell-escaping is lost from any options or-arguments intended for by the add-on command, so those need an extra-level of shell-escaping.  Eg to match a literal '$' sign while using the-bash shell and running an add-on command ('ui'):--$ hledger ui cur:'\\$'--   or:--$ hledger ui cur:\\\\$--   If you wondered why _four_ backslashes, perhaps this helps:--unescaped:        '$'-escaped:          '\$'-double-escaped:   '\\$'-triple-escaped:   '\\\\$'--   Or, you can avoid the extra escaping by running the add-on executable-directly:--$ hledger-ui cur:\\$---File: hledger.info,  Node: Less escaping,  Prev: Triple escaping for add-on commands,  Up: Special characters--1.4.4 Less escaping----------------------Options and arguments are sometimes used in places other than the shell-command line, where shell-escaping is not needed, so there you should-use one less level of escaping.  Those places include:--   * an @argumentfile-   * hledger-ui's filter field-   * hledger-web's search form-   * GHCI's prompt (used by developers).---File: hledger.info,  Node: Unicode characters,  Next: Regular expressions,  Prev: Special characters,  Up: OPTIONS--1.5 Unicode characters-======================--hledger is expected to handle non-ascii characters correctly:--   * they should be parsed correctly in input files and on the command-     line, by all hledger tools (add, iadd, hledger-web's-     search/add/edit forms, etc.)--   * they should be displayed correctly by all hledger tools, and-     on-screen alignment should be preserved.--   This requires a well-configured environment.  Here are some tips:--   * A system locale must be configured, and it must be one that can-     decode the characters being used.  In bash, you can set a locale-     like this: 'export LANG=en_US.UTF-8'.  There are some more details-     in Troubleshooting.  This step is essential - without it, hledger-     will quit on encountering a non-ascii character (as with all-     GHC-compiled programs).--   * your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..)-     must support unicode--   * the terminal must be using a font which includes the required-     unicode glyphs--   * the terminal should be configured to display wide characters as-     double width (for report alignment)--   * on Windows, for best results you should run hledger in the same-     kind of environment in which it was built.  Eg hledger built in the-     standard CMD.EXE environment (like the binaries on our download-     page) might show display problems when run in a cygwin or msys-     terminal, and vice versa.  (See eg #961).---File: hledger.info,  Node: Regular expressions,  Prev: Unicode characters,  Up: OPTIONS--1.6 Regular expressions-=======================--hledger uses regular expressions in a number of places:--   * query terms, on the command line and in the hledger-web search-     form: 'REGEX', 'desc:REGEX', 'cur:REGEX', 'tag:...=REGEX'-   * CSV rules conditional blocks: 'if REGEX ...'-   * account alias directives and options: 'alias /REGEX/ =-     REPLACEMENT', '--alias /REGEX/=REPLACEMENT'--   hledger's regular expressions come from the regex-tdfa library.  If-they're not doing what you expect, it's important to know exactly what-they support:--  1. they are case insensitive-  2. they are infix matching (they do not need to match the entire thing-     being matched)-  3. they are POSIX ERE (extended regular expressions)-  4. they also support GNU word boundaries ('\b', '\B', '\<', '\>')-  5. they do not support backreferences; if you write '\1', it will-     match the digit '1'.  Except when doing text replacement, eg in-     account aliases, where backreferences can be used in the-     replacement string to reference capturing groups in the search-     regexp.-  6. they do not support mode modifiers ('(?s)'), character classes-     ('\w', '\d'), or anything else not mentioned above.--   Some things to note:--   * In the 'alias' directive and '--alias' option, regular expressions-     must be enclosed in forward slashes ('/REGEX/').  Elsewhere in-     hledger, these are not required.--   * In queries, to match a regular expression metacharacter like '$' as-     a literal character, prepend a backslash.  Eg to search for amounts-     with the dollar sign in hledger-web, write 'cur:\$'.--   * On the command line, some metacharacters like '$' have a special-     meaning to the shell and so must be escaped at least once more.-     See Special characters.---File: hledger.info,  Node: ENVIRONMENT,  Next: DATA FILES,  Prev: OPTIONS,  Up: Top--2 ENVIRONMENT-*************--*LEDGER_FILE* The journal file path when not specified with '-f'.--   On unix computers, the default value is: '~/.hledger.journal'.--   A more typical value is something like '~/finance/YYYY.journal',-where '~/finance' is a version-controlled finance directory and YYYY is-the current year.  Or, '~/finance/current.journal', where-current.journal is a symbolic link to YYYY.journal.--   The usual way to set this permanently is to add a command to one of-your shell's startup files (eg '~/.profile'):--export LEDGER_FILE=~/finance/current.journal`--   On some Mac computers, there is a more thorough way to set-environment variables, that will also affect applications started from-the GUI (eg, Emacs started from a dock icon): In-'~/.MacOSX/environment.plist', add an entry like:--{-  "LEDGER_FILE" : "~/finance/current.journal"-}--   For this to take effect you might need to 'killall Dock', or reboot.--   On Windows computers, the default value is probably-'C:\Users\MyUserName\.hledger.journal'.  You can change this by running-a command like this in a powershell window:--> setx LEDGER_FILE "C:\Users\MyUserName\finance\2021.journal"--   (Let us know if you need to be an Administrator, and if this persists-across a reboot.)--   *COLUMNS* The screen width used by the register command.  Default:-the full terminal width.--   *NO_COLOR* If this variable exists with any value, hledger will not-use ANSI color codes in terminal output.  This is overriden by the--color/-colour option.---File: hledger.info,  Node: DATA FILES,  Next: TIME PERIODS,  Prev: ENVIRONMENT,  Up: Top--3 DATA FILES-************--hledger reads transactions from one or more data files.  The default-data file is '$HOME/.hledger.journal' (or on Windows, something like-'C:/Users/USER/.hledger.journal').--   You can override this with the '$LEDGER_FILE' environment variable:--$ setenv LEDGER_FILE ~/finance/2016.journal-$ hledger stats--   or with one or more '-f/--file' options:--$ hledger -f /some/file -f another_file stats--   The file name '-' means standard input:--$ cat some.journal | hledger -f---* Menu:--* Data formats::-* Multiple files::-* Strict mode::---File: hledger.info,  Node: Data formats,  Next: Multiple files,  Up: DATA FILES--3.1 Data formats-================--Usually the data file is in hledger's journal format, but it can be in-any of the supported file formats, which currently are:--Reader:  Reads:                                   Used for file-                                                  extensions:----------------------------------------------------------------------------'journal'hledger journal files and some Ledger    '.journal' '.j'-         journals, for transactions               '.hledger' '.ledger'-'timeclock'timeclock files, for precise time      '.timeclock'-         logging-'timedot'timedot files, for approximate time      '.timedot'-         logging-'csv'    comma/semicolon/tab/other-separated      '.csv' '.ssv' '.tsv'-         values, for data import--   These formats are described in their own sections, below.--   hledger detects the format automatically based on the file extensions-shown above.  If it can't recognise the file extension, it assumes-'journal' format.  So for non-journal files, it's important to use a-recognised file extension, so as to either read successfully or to show-relevant error messages.--   You can also force a specific reader/format by prefixing the file-path with the format and a colon.  Eg, to read a .dat file as csv-format:--$ hledger -f csv:/some/csv-file.dat stats--   Or to read stdin ('-') as timeclock format:--$ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:----File: hledger.info,  Node: Multiple files,  Next: Strict mode,  Prev: Data formats,  Up: DATA FILES--3.2 Multiple files-==================--You can specify multiple '-f' options, to read multiple files as one big-journal.  There are some limitations with this:--   * most directives do not affect sibling files-   * balance assertions will not see any account balances from previous-     files--   If you need either of those things, you can--   * use a single parent file which includes the others-   * or concatenate the files into one before reading, eg: 'cat-     a.journal b.journal | hledger -f- CMD'.---File: hledger.info,  Node: Strict mode,  Prev: Multiple files,  Up: DATA FILES--3.3 Strict mode-===============--hledger checks input files for valid data.  By default, the most-important errors are detected, while still accepting easy journal files-without a lot of declarations:--   * Are the input files parseable, with valid syntax ?-   * Are all transactions balanced ?-   * Do all balance assertions pass ?--   With the '-s'/'--strict' flag, additional checks are performed:--   * Are all accounts posted to, declared with an 'account' directive ?-     (Account error checking)-   * Are all commodities declared with a 'commodity' directive ?-     (Commodity error checking)-   * Are all commodity conversions declared explicitly ?--   You can also use the check command to run these and some additional-checks.---File: hledger.info,  Node: TIME PERIODS,  Next: DEPTH,  Prev: DATA FILES,  Up: Top--4 TIME PERIODS-**************--* Menu:--* Smart dates::-* Report start & end date::-* Report intervals::-* Period expressions::---File: hledger.info,  Node: Smart dates,  Next: Report start & end date,  Up: TIME PERIODS--4.1 Smart dates-===============--hledger's user interfaces accept a flexible "smart date" syntax.  Smart-dates allow some english words, can be relative to today's date, and can-have less-significant date parts omitted (defaulting to 1).--   Examples:--'2004/10/1',              exact date, several separators allowed.  Year-'2004-01-01',             is 4+ digits, month is 1-12, day is 1-31-'2004.9.1'-'2004'                    start of year-'2004/10'                 start of month-'10/1'                    month and day in current year-'21'                      day in current month-'october, oct'            start of month in current year-'yesterday, today,        -1, 0, 1 days from today-tomorrow'-'last/this/next           -1, 0, 1 periods from the current period-day/week/month/quarter/year'-'20181201'                8 digit YYYYMMDD with valid year month and-                          day-'201812'                  6 digit YYYYMM with valid year and month--   Counterexamples - malformed digit sequences might give surprising-results:--'201813'     6 digits with an invalid month is parsed as start of-             6-digit year-'20181301'   8 digits with an invalid month is parsed as start of-             8-digit year-'20181232'   8 digits with an invalid day gives an error-'201801012'  9+ digits beginning with a valid YYYYMMDD gives an error--   Note "today's date" can be overridden with the '--today' option, in-case it's needed for testing or for recreating old reports.  (Except for-periodic transaction rules; those are not affected by '--today'.)---File: hledger.info,  Node: Report start & end date,  Next: Report intervals,  Prev: Smart dates,  Up: TIME PERIODS--4.2 Report start & end date-===========================--By default, most hledger reports will show the full span of time-represented by the journal data.  The report start date will be the-earliest transaction or posting date, and the report end date will be-the latest transaction, posting, or market price date.--   Often you will want to see a shorter time span, such as the current-month.  You can specify a start and/or end date using '-b/--begin',-'-e/--end', '-p/--period' or a 'date:' query (described below).  All of-these accept the smart date syntax.--   Some notes:--   * End dates are exclusive, as in Ledger, so you should write the date-     _after_ the last day you want to see in the report.-   * As noted in reporting options: among start/end dates specified with-     _options_, the last (i.e.  right-most) option takes precedence.-   * The effective report start and end dates are the intersection of-     the start/end dates from options and that from 'date:' queries.-     That is, 'date:2019-01 date:2019 -p'2000 to 2030'' yields January-     2019, the smallest common time span.-   * A report interval (see below) will adjust start/end dates, when-     needed, so that they fall on subperiod boundaries.--   Examples:--'-b           begin on St. Patrick's day 2016-2016/3/17'-'-e 12/1'     end at the start of december 1st of the current year-              (11/30 will be the last date included)-'-b           all transactions on or after the 1st of the current month-thismonth'-'-p           all transactions in the current month-thismonth'-'date:2016/3/17..'the above written as queries instead ('..' can also be-              replaced with '-')-'date:..12/1'-'date:thismonth..'-'date:thismonth'---File: hledger.info,  Node: Report intervals,  Next: Period expressions,  Prev: Report start & end date,  Up: TIME PERIODS--4.3 Report intervals-====================--A report interval can be specified so that commands like register,-balance and activity become multi-period, showing each subperiod as a-separate row or column.--   The following "standard" report intervals can be enabled by using-their corresponding flag:--   * '-D/--daily'-   * '-W/--weekly'-   * '-M/--monthly'-   * '-Q/--quarterly'-   * '-Y/--yearly'--   These standard intervals always start on natural interval boundaries:-eg '--weekly' starts on mondays, '--monthly' starts on the first of the-month, '--yearly' always starts on January 1st, etc.--   Certain more complex intervals, and more flexible boundary dates, can-be specified by '-p/--period'.  These are described in period-expressions, below.--   Report intervals can only be specified by the flags above, and not by-query arguments, currently.--   Report intervals have another effect: multi-period reports are always-expanded to fill a whole number of subperiods.  So if you use a report-interval (other than '--daily'), and you have specified a start or end-date, you may notice those dates being overridden (ie, the report starts-earlier than your requested start date, or ends later than your-requested end date).  This is done to ensure "full" first and last-subperiods, so that all subperiods' numbers are comparable.--   To summarise:--   * In multiperiod reports, all subperiods are forced to be the same-     length, to simplify reporting.-   * Reports with the standard-     '--weekly'/'--monthly'/'--quarterly'/'--yearly' intervals are-     required to start on the first day of a week/month/quarter/year.-     We'd like more flexibility here but it isn't supported yet.-   * '--period' (below) can specify more complex intervals, starting on-     any date.---File: hledger.info,  Node: Period expressions,  Prev: Report intervals,  Up: TIME PERIODS--4.4 Period expressions-======================--The '-p/--period' option accepts period expressions, a shorthand way of-expressing a start date, end date, and/or report interval all at once.--   Here's a basic period expression specifying the first quarter of-2009.  Note, hledger always treats start dates as inclusive and end-dates as exclusive:--'-p "from 2009/1/1 to 2009/4/1"'--   Keywords like "from" and "to" are optional, and so are the spaces, as-long as you don't run two dates together.  "to" can also be written as-".."  or "-".  These are equivalent to the above:--'-p "2009/1/1 2009/4/1"'-'-p2009/1/1to2009/4/1'-'-p2009/1/1..2009/4/1'--   Dates are smart dates, so if the current year is 2009, the above can-also be written as:--'-p "1/1 4/1"'-'-p "january-apr"'-'-p "this year to 4/1"'--   If you specify only one date, the missing start or end date will be-the earliest or latest transaction in your journal:--'-p "from 2009/1/1"'   everything after january 1, 2009-'-p "from 2009/1"'     the same-'-p "from 2009"'       the same-'-p "to 2009"'         everything before january 1, 2009--   A single date with no "from" or "to" defines both the start and end-date like so:--'-p "2009"'       the year 2009; equivalent to “2009/1/1 to 2010/1/1”-'-p "2009/1"'     the month of jan; equivalent to “2009/1/1 to 2009/2/1”-'-p "2009/1/1"'   just that day; equivalent to “2009/1/1 to 2009/1/2”--   Or you can specify a single quarter like so:--'-p "2009Q1"'   first quarter of 2009, equivalent to “2009/1/1 to 2009/4/1”-'-p "q4"'       fourth quarter of the current year--* Menu:--* Period expressions with a report interval::-* More complex report intervals::-* Intervals with custom start date::-* Periods or dates ?::-* Events on multiple weekdays::---File: hledger.info,  Node: Period expressions with a report interval,  Next: More complex report intervals,  Up: Period expressions--4.4.1 Period expressions with a report interval--------------------------------------------------'-p/--period''s argument can also begin with, or entirely consist of, a-report interval.  This should be separated from the start/end dates (if-any) by a space, or the word 'in'.  The basic intervals (which can also-be written as command line flags) are 'daily', 'weekly', 'monthly',-'quarterly', and 'yearly'.  Some examples:--'-p "weekly from 2009/1/1 to 2009/4/1"'-'-p "monthly in 2008"'-'-p "quarterly"'--   As mentioned above, the 'weekly', 'monthly', 'quarterly' and 'yearly'-intervals require a report start date that is the first day of a week,-month, quarter or year.  And, report start/end dates will be expanded if-needed to span a whole number of intervals.--   For example:--'-p "weekly from           starts on 2008/12/29, closest preceding-2009/1/1 to 2009/4/1"'     Monday-'-p "monthly in            starts on 2018/11/01-2008/11/25"'-'-p "quarterly from        starts on 2009/04/01, ends on 2009/06/30,-2009-05-05 to              which are first and last days of Q2 2009-2009-06-01"'-'-p "yearly from           starts on 2009/01/01, first day of 2009-2009-12-29"'---File: hledger.info,  Node: More complex report intervals,  Next: Intervals with custom start date,  Prev: Period expressions with a report interval,  Up: Period expressions--4.4.2 More complex report intervals--------------------------------------Some more complex kinds of interval are also supported in period-expressions:--   * 'biweekly'-   * 'fortnightly'-   * 'bimonthly'-   * 'every day|week|month|quarter|year'-   * 'every N days|weeks|months|quarters|years'--   These too will cause report start/end dates to be expanded, if-needed, to span a whole number of intervals.  Examples:--'-p "bimonthly from        periods will have boundaries on 2008/01/01,-2008"'                     2008/03/01, ...-'-p "every 2 weeks"'       starts on closest preceding Monday-'-p "every 5 month from    periods will have boundaries on 2009/03/01,-2009/03"'                  2009/08/01, ...---File: hledger.info,  Node: Intervals with custom start date,  Next: Periods or dates ?,  Prev: More complex report intervals,  Up: Period expressions--4.4.3 Intervals with custom start date-----------------------------------------All intervals mentioned above are required to start on their natural-calendar boundaries, but the following intervals can start on any date:--   Weekly on custom day:--   * 'every Nth day of week' ('th', 'nd', 'rd', or 'st' are all accepted-     after the number)-   * 'every WEEKDAYNAME' (full or three-letter english weekday name,-     case insensitive)--   Monthly on custom day:--   * 'every Nth day [of month]'-   * 'every Nth WEEKDAYNAME [of month]'--   Yearly on custom day:--   * 'every MM/DD [of year]' (month number and day of month number)-   * 'every MONTHNAME DDth [of year]' (full or three-letter english-     month name, case insensitive, and day of month number)-   * 'every DDth MONTHNAME [of year]' (equivalent to the above)--   Examples:--'-p "every 2nd day of    periods will go from Tue to Tue-week"'-'-p "every Tue"'         same-'-p "every 15th day"'    period boundaries will be on 15th of each-                         month-'-p "every 2nd           period boundaries will be on second Monday of-Monday"'                 each month-'-p "every 11/05"'       yearly periods with boundaries on 5th of-                         November-'-p "every 5th           same-November"'-'-p "every Nov 5th"'     same--   Show historical balances at end of the 15th day of each month (N is-an end date, exclusive as always):--$ hledger balance -H -p "every 16th day"--   Group postings from the start of wednesday to end of the following-tuesday (N is both (inclusive) start date and (exclusive) end date):--$ hledger register checking -p "every 3rd day of week"---File: hledger.info,  Node: Periods or dates ?,  Next: Events on multiple weekdays,  Prev: Intervals with custom start date,  Up: Period expressions--4.4.4 Periods or dates ?---------------------------Report intervals like the above are most often used with '-p|--period',-to divide reports into multiple subperiods - each generated date marks a-subperiod boundary.  Here, the periods between the dates are what's-important.--   But report intervals can also be used with '--forecast' to generate-future transactions, or with 'balance --budget' to generate budget-goal-setting transactions.  For these, the dates themselves are what-matters.---File: hledger.info,  Node: Events on multiple weekdays,  Prev: Periods or dates ?,  Up: Period expressions--4.4.5 Events on multiple weekdays------------------------------------The 'every WEEKDAYNAME' form has a special variant with multiple day-names, comma-separated.  Eg: 'every mon,thu,sat'.  Also, 'weekday' and-'weekendday' are shorthand for 'mon,tue,wed,thu,fri' and 'sat,sun'-respectively.--   This form is mainly intended for use with '--forecast', to generate-periodic transactions on arbitrary days of the week.  It may be less-useful with '-p', since it divides each week into subperiods of unequal-length.  (Because gaps between periods are not allowed; if you'd like to-change this, see #1632.)--   Examples:--'-p "every         dates will be Mon, Wed, Fri; periods will be-mon,wed,fri"'      Mon-Tue, Wed-Thu, Fri-Sun-'-p "every         dates will be Mon, Tue, Wed, Thu, Fri; periods will-weekday"'          be Mon, Tue, Wed, Thu, Fri-Sun-'-p "every         dates will be Sat, Sun; periods will be Sat, Sun-Fri-weekendday"'---File: hledger.info,  Node: DEPTH,  Next: QUERIES,  Prev: TIME PERIODS,  Up: Top--5 DEPTH-*******--With the '--depth NUM' option (short form: '-NUM'), commands like-account, balance and register will show only the uppermost accounts in-the account tree, down to level NUM. Use this when you want a summary-with less detail.  This flag has the same effect as a 'depth:' query-argument: 'depth:2', '--depth=2' or '-2' are equivalent.---File: hledger.info,  Node: QUERIES,  Next: COSTING,  Prev: DEPTH,  Up: Top--6 QUERIES-*********--One of hledger's strengths is being able to quickly report on a precise-subset of your data.  Most hledger commands accept optional query-arguments to restrict their scope.  The syntax is as follows:--   * Zero or more space-separated query terms.  These are most often-     account name substrings:--     'utilities food:groceries'--   * Terms with spaces or other special characters should be enclosed in-     quotes:--     '"personal care"'--   * Regular expressions are also supported:--     '"^expenses\b" "accounts (payable|receivable)"'--   * Add a query type prefix to match other parts of the data:--     'date:202012- desc:amazon cur:USD amt:">100" status:'--   * Add a 'not:' prefix to negate a term:--     'not:cur:USD'--* Menu:--* Query types::-* Combining query terms::-* Queries and command options::-* Queries and account aliases::-* Queries and valuation::-* Querying with account aliases::-* Querying with cost or value::---File: hledger.info,  Node: Query types,  Next: Combining query terms,  Up: QUERIES--6.1 Query types-===============--Here are the types of query term available.  Remember these can also be-prefixed with *'not:'* to convert them into a negative match.--   *'acct:REGEX', 'REGEX'*-Match account names containing this (case insensitive) regular-expression.  This is the default query type when there is no prefix, and-regular expression syntax is typically not needed, so usually we just-write an account name substring, like 'expenses' or 'food'.--   *'amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N'*-Match postings with a single-commodity amount equal to, less than, or-greater than N. (Postings with multi-commodity amounts are not tested-and will always match.)  The comparison has two modes: if N is preceded-by a + or - sign (or is 0), the two signed numbers are compared.-Otherwise, the absolute magnitudes are compared, ignoring sign.--   *'code:REGEX'*-Match by transaction code (eg check number).--   *'cur:REGEX'*-Match postings or transactions including any amounts whose-currency/commodity symbol is fully matched by REGEX. (For a partial-match, use '.*REGEX.*').  Note, to match special characters which are-regex-significant, you need to escape them with '\'.  And for characters-which are significant to your shell you may need one more level of-escaping.  So eg to match the dollar sign:-'hledger print cur:\\$'.--   *'desc:REGEX'*-Match transaction descriptions.--   *'date:PERIODEXPR'*-Match dates (or with the '--date2' flag, secondary dates) within the-specified period.  PERIODEXPR is a period expression with no report-interval.  Examples:-'date:2016', 'date:thismonth', 'date:2/1-2/15',-'date:2021-07-27..nextquarter'.--   *'date2:PERIODEXPR'*-Match secondary dates within the specified period (independent of the-'--date2' flag).--   *'depth:N'*-Match (or display, depending on command) accounts at or above this-depth.--   *'note:REGEX'*-Match transaction notes (the part of the description right of '|', or-the whole description if there's no '|').--   *'payee:REGEX'*-Match transaction payee/payer names (the part of the description left of-'|', or the whole description if there's no '|').--   *'real:, real:0'*-Match real or virtual postings respectively.--   *'status:, status:!, status:*'*-Match unmarked, pending, or cleared transactions respectively.--   *'tag:REGEX[=REGEX]'*-Match by tag name, and optionally also by tag value.  (To match only by-value, use 'tag:.=REGEX'.)  Note that postings also inherit tags from-their transaction, and transactions also acquire tags from their-postings, when querying.--   (*'inacct:ACCTNAME'*-A special query term used automatically in hledger-web only: tells-hledger-web to show the transaction register for an account.)---File: hledger.info,  Node: Combining query terms,  Next: Queries and command options,  Prev: Query types,  Up: QUERIES--6.2 Combining query terms-=========================--Most commands select things which match:--   * any of the description terms AND-   * any of the account terms AND-   * any of the status terms AND-   * all the other terms.--   while the print command shows transactions which:--   * match any of the description terms AND-   * have any postings matching any of the positive account terms AND-   * have no postings matching any of the negative account terms AND-   * match all the other terms.--   You can do more powerful queries (such as AND-ing two like terms) by-running a first query with 'print', and piping the result into a second-hledger command.  Eg: how much of food expenses was paid with cash ?--$ hledger print assets:cash | hledger -f- -I balance expenses:food--   If you are interested in full boolean expressions for queries, see-#203.---File: hledger.info,  Node: Queries and command options,  Next: Queries and account aliases,  Prev: Combining query terms,  Up: QUERIES--6.3 Queries and command options-===============================--Some queries can also be expressed as command-line options: 'depth:2' is-equivalent to '--depth 2', 'date:2020' is equivalent to '-p 2020', etc.-When you mix command options and query arguments, generally the-resulting query is their intersection.---File: hledger.info,  Node: Queries and account aliases,  Next: Queries and valuation,  Prev: Queries and command options,  Up: QUERIES--6.4 Queries and account aliases-===============================--When account names are rewritten with '--alias' or 'alias', 'acct:' will-match either the old or the new account name.---File: hledger.info,  Node: Queries and valuation,  Next: Querying with account aliases,  Prev: Queries and account aliases,  Up: QUERIES--6.5 Queries and valuation-=========================--When amounts are converted to other commodities in cost or value-reports, 'cur:' and 'amt:' match the old commodity symbol and the old-amount quantity, not the new ones (except in hledger 1.22.0 where it's-reversed, see #1625).---File: hledger.info,  Node: Querying with account aliases,  Next: Querying with cost or value,  Prev: Queries and valuation,  Up: QUERIES--6.6 Querying with account aliases-=================================--When account names are rewritten with '--alias' or 'alias', note that-'acct:' will match either the old or the new account name.---File: hledger.info,  Node: Querying with cost or value,  Prev: Querying with account aliases,  Up: QUERIES--6.7 Querying with cost or value-===============================--When amounts are converted to other commodities in cost or value-reports, note that 'cur:' matches the new commodity symbol, and not the-old one, and 'amt:' matches the new quantity, and not the old one.-Note: this changed in hledger 1.22, previously it was the reverse, see-the discussion at #1625.---File: hledger.info,  Node: COSTING,  Next: VALUATION,  Prev: QUERIES,  Up: Top--7 COSTING-*********--The '-B/--cost' flag converts amounts to their cost or sale amount at-transaction time, if they have a transaction price specified.  If this-flag is supplied, hledger will perform cost conversion first, and will-apply any market price valuations (if requested) afterwards.---File: hledger.info,  Node: VALUATION,  Next: PIVOTING,  Prev: COSTING,  Up: Top--8 VALUATION-***********--Instead of reporting amounts in their original commodity, hledger can-convert them to cost/sale amount (using the conversion rate recorded in-the transaction), and/or to market value (using some market price on a-certain date).  This is controlled by the '--value=TYPE[,COMMODITY]'-option, which will be described below.  We also provide the simpler '-V'-and '-X COMMODITY' options, and often one of these is all you need:--* Menu:--* -V Value::-* -X Value in specified commodity::-* Valuation date::-* Market prices::-* --infer-market-prices market prices from transactions::-* Valuation commodity::-* Simple valuation examples::-* --value Flexible valuation::-* More valuation examples::-* Interaction of valuation and queries::-* Effect of valuation on reports::---File: hledger.info,  Node: -V Value,  Next: -X Value in specified commodity,  Up: VALUATION--8.1 -V: Value-=============--The '-V/--market' flag converts amounts to market value in their default-_valuation commodity_, using the market prices in effect on the-_valuation date(s)_, if any.  More on these in a minute.---File: hledger.info,  Node: -X Value in specified commodity,  Next: Valuation date,  Prev: -V Value,  Up: VALUATION--8.2 -X: Value in specified commodity-====================================--The '-X/--exchange=COMM' option is like '-V', except you tell it which-currency you want to convert to, and it tries to convert everything to-that.---File: hledger.info,  Node: Valuation date,  Next: Market prices,  Prev: -X Value in specified commodity,  Up: VALUATION--8.3 Valuation date-==================--Since market prices can change from day to day, market value reports-have a valuation date (or more than one), which determines which market-prices will be used.--   For single period reports, if an explicit report end date is-specified, that will be used as the valuation date; otherwise the-valuation date is the journal's end date.--   For multiperiod reports, each column/period is valued on the last day-of the period, by default.---File: hledger.info,  Node: Market prices,  Next: --infer-market-prices market prices from transactions,  Prev: Valuation date,  Up: VALUATION--8.4 Market prices-=================--To convert a commodity A to its market value in another commodity B,-hledger looks for a suitable market price (exchange rate) as follows, in-this order of preference :--  1. A _declared market price_ or _inferred market price_: A's latest-     market price in B on or before the valuation date as declared by a-     P directive, or (with the '--infer-market-prices' flag) inferred-     from transaction prices.--  2. A _reverse market price_: the inverse of a declared or inferred-     market price from B to A.--  3. A _forward chain of market prices_: a synthetic price formed by-     combining the shortest chain of "forward" (only 1 above) market-     prices, leading from A to B.--  4. _Any chain of market prices_: a chain of any market prices,-     including both forward and reverse prices (1 and 2 above), leading-     from A to B.--   There is a limit to the length of these price chains; if hledger-reaches that length without finding a complete chain or exhausting all-possibilities, it will give up (with a "gave up" message visible in-'--debug=2' output).  That limit is currently 1000.--   Amounts for which no suitable market price can be found, are not-converted.---File: hledger.info,  Node: --infer-market-prices market prices from transactions,  Next: Valuation commodity,  Prev: Market prices,  Up: VALUATION--8.5 -infer-market-prices: market prices from transactions-=========================================================--Normally, market value in hledger is fully controlled by, and requires,-P directives in your journal.  Since adding and updating those can be a-chore, and since transactions usually take place at close to market-value, why not use the recorded transaction prices as additional market-prices (as Ledger does) ?  We could produce value reports without-needing P directives at all.--   Adding the '--infer-market-prices' flag to '-V', '-X' or '--value'-enables this.  So for example, 'hledger bs -V --infer-market-prices'-will get market prices both from P directives and from transactions.-(And if both occur on the same day, the P directive takes precedence).--   There is a downside: value reports can sometimes be affected in-confusing/undesired ways by your journal entries.  If this happens to-you, read all of this Valuation section carefully, and try adding-'--debug' or '--debug=2' to troubleshoot.--   '--infer-market-prices' can infer market prices from:--   * multicommodity transactions with explicit prices ('@'/'@@')--   * multicommodity transactions with implicit prices (no '@', two-     commodities, unbalanced).  (With these, the order of postings-     matters.  'hledger print -x' can be useful for troubleshooting.)--   * but not, currently, from "more correct" multicommodity transactions-     (no '@', multiple commodities, balanced).---File: hledger.info,  Node: Valuation commodity,  Next: Simple valuation examples,  Prev: --infer-market-prices market prices from transactions,  Up: VALUATION--8.6 Valuation commodity-=======================--*When you specify a valuation commodity ('-X COMM' or '--value-TYPE,COMM'):*-hledger will convert all amounts to COMM, wherever it can find a-suitable market price (including by reversing or chaining prices).--   *When you leave the valuation commodity unspecified ('-V' or '--value-TYPE'):*-For each commodity A, hledger picks a default valuation commodity as-follows, in this order of preference:--  1. The price commodity from the latest P-declared market price for A-     on or before valuation date.--  2. The price commodity from the latest P-declared market price for A-     on any date.  (Allows conversion to proceed when there are inferred-     prices before the valuation date.)--  3. If there are no P directives at all (any commodity or date) and the-     '--infer-market-prices' flag is used: the price commodity from the-     latest transaction-inferred price for A on or before valuation-     date.--   This means:--   * If you have P directives, they determine which commodities '-V'-     will convert, and to what.--   * If you have no P directives, and use the '--infer-market-prices'-     flag, transaction prices determine it.--   Amounts for which no valuation commodity can be found are not-converted.---File: hledger.info,  Node: Simple valuation examples,  Next: --value Flexible valuation,  Prev: Valuation commodity,  Up: VALUATION--8.7 Simple valuation examples-=============================--Here are some quick examples of '-V':--; one euro is worth this many dollars from nov 1-P 2016/11/01 € $1.10--; purchase some euros on nov 3-2016/11/3-    assets:euros        €100-    assets:checking--; the euro is worth fewer dollars by dec 21-P 2016/12/21 € $1.03--   How many euros do I have ?--$ hledger -f t.j bal -N euros-                €100  assets:euros--   What are they worth at end of nov 3 ?--$ hledger -f t.j bal -N euros -V -e 2016/11/4-             $110.00  assets:euros--   What are they worth after 2016/12/21 ?  (no report end date-specified, defaults to today)--$ hledger -f t.j bal -N euros -V-             $103.00  assets:euros---File: hledger.info,  Node: --value Flexible valuation,  Next: More valuation examples,  Prev: Simple valuation examples,  Up: VALUATION--8.8 -value: Flexible valuation-==============================--'-V' and '-X' are special cases of the more general '--value' option:-- --value=TYPE[,COMM]  TYPE is then, end, now or YYYY-MM-DD.-                      COMM is an optional commodity symbol.-                      Shows amounts converted to:-                      - default valuation commodity (or COMM) using market prices at posting dates-                      - default valuation commodity (or COMM) using market prices at period end(s)-                      - default valuation commodity (or COMM) using current market prices-                      - default valuation commodity (or COMM) using market prices at some date--   The TYPE part selects cost or value and valuation date:--'--value=then'--     Convert amounts to their value in the default valuation commodity,-     using market prices on each posting's date.-'--value=end'--     Convert amounts to their value in the default valuation commodity,-     using market prices on the last day of the report period (or if-     unspecified, the journal's end date); or in multiperiod reports,-     market prices on the last day of each subperiod.-'--value=now'--     Convert amounts to their value in the default valuation commodity-     using current market prices (as of when report is generated).-'--value=YYYY-MM-DD'--     Convert amounts to their value in the default valuation commodity-     using market prices on this date.--   To select a different valuation commodity, add the optional ',COMM'-part: a comma, then the target commodity's symbol.  Eg:-*'--value=now,EUR'*.  hledger will do its best to convert amounts to-this commodity, deducing market prices as described above.---File: hledger.info,  Node: More valuation examples,  Next: Interaction of valuation and queries,  Prev: --value Flexible valuation,  Up: VALUATION--8.9 More valuation examples-===========================--Here are some examples showing the effect of '--value', as seen with-'print':--P 2000-01-01 A  1 B-P 2000-02-01 A  2 B-P 2000-03-01 A  3 B-P 2000-04-01 A  4 B--2000-01-01-  (a)      1 A @ 5 B--2000-02-01-  (a)      1 A @ 6 B--2000-03-01-  (a)      1 A @ 7 B--   Show the cost of each posting:--$ hledger -f- print --cost-2000-01-01-    (a)             5 B--2000-02-01-    (a)             6 B--2000-03-01-    (a)             7 B--   Show the value as of the last day of the report period (2000-02-29):--$ hledger -f- print --value=end date:2000/01-2000/03-2000-01-01-    (a)             2 B--2000-02-01-    (a)             2 B--   With no report period specified, that shows the value as of the last-day of the journal (2000-03-01):--$ hledger -f- print --value=end-2000-01-01-    (a)             3 B--2000-02-01-    (a)             3 B--2000-03-01-    (a)             3 B--   Show the current value (the 2000-04-01 price is still in effect-today):--$ hledger -f- print --value=now-2000-01-01-    (a)             4 B--2000-02-01-    (a)             4 B--2000-03-01-    (a)             4 B--   Show the value on 2000/01/15:--$ hledger -f- print --value=2000-01-15-2000-01-01-    (a)             1 B--2000-02-01-    (a)             1 B--2000-03-01-    (a)             1 B--   You may need to explicitly set a commodity's display style, when-reverse prices are used.  Eg this output might be surprising:--P 2000-01-01 A 2B--2000-01-01-  a  1B-  b--$ hledger print -x -X A-2000-01-01-    a               0-    b               0--   Explanation: because there's no amount or commodity directive-specifying a display style for A, 0.5A gets the default style, which-shows no decimal digits.  Because the displayed amount looks like zero,-the commodity symbol and minus sign are not displayed either.  Adding a-commodity directive sets a more useful display style for A:--P 2000-01-01 A 2B-commodity 0.00A--2000-01-01-  a  1B-  b--$ hledger print -X A-2000-01-01-    a           0.50A-    b          -0.50A---File: hledger.info,  Node: Interaction of valuation and queries,  Next: Effect of valuation on reports,  Prev: More valuation examples,  Up: VALUATION--8.10 Interaction of valuation and queries-=========================================--When matching postings based on queries in the presence of valuation,-the following happens.--  1. The query is separated into two parts:-       1. the currency ('cur:') or amount ('amt:').-       2. all other parts.--  2. The postings are matched to the currency and amount queries based-     on pre-valued amounts.-  3. Valuation is applied to the postings.-  4. The postings are matched to the other parts of the query based on-     post-valued amounts.--   See: 1625---File: hledger.info,  Node: Effect of valuation on reports,  Prev: Interaction of valuation and queries,  Up: VALUATION--8.11 Effect of valuation on reports-===================================--Here is a reference for how valuation is supposed to affect each part of-hledger's reports (and a glossary).  (It's wide, you'll have to scroll-sideways.)  It may be useful when troubleshooting.  If you find-problems, please report them, ideally with a reproducible example.-Related: #329, #1083.--Report     '-B',        '-V', '-X'   '--value=then'     '--value=end''--value=DATE',-type       '--cost'                                                  '--value=now'--------------------------------------------------------------------------------*print*-posting    cost         value at     value at posting   value at     value-amounts                 report end   date               report or    at-                        or today                        journal      DATE/today-                                                        end-balance    unchanged    unchanged    unchanged          unchanged    unchanged-assertions/assignments-*register*-starting   cost         value at     valued at day      value at     value-balance                 report or    each historical    report or    at-(-H)                    journal      posting was made   journal      DATE/today-                        end                             end-starting   cost         value at     valued at day      value at     value-balance                 day before   each historical    day before   at-(-H)                    report or    posting was made   report or    DATE/today-with                    journal                         journal-report                  start                           start-interval-posting    cost         value at     value at posting   value at     value-amounts                 report or    date               report or    at-                        journal                         journal      DATE/today-                        end                             end-summary    summarised   value at     sum of postings    value at     value-posting    cost         period       in interval,       period       at-amounts                 ends         valued at          ends         DATE/today-with                                 interval start-report-interval-running    sum/average  sum/average  sum/average of     sum/average  sum/average-total/averageof         of           displayed values   of           of-           displayed    displayed                       displayed    displayed-           values       values                          values       values-*balance-(bs,-bse, cf,-is)*-balance    sums of      value at     value at posting   value at     value-changes    costs        report end   date               report or    at-                        or today                        journal      DATE/today-                        of sums of                      end of       of-                        postings                        sums of      sums-                                                        postings     of-                                                                     postings-budget     like         like         like balance       like         like-amounts    balance      balance      changes            balances     balance-(-budget)  changes      changes                                      changes-grand      sum of       sum of       sum of displayed   sum of       sum of-total      displayed    displayed    valued             displayed    displayed-           values       values                          values       values-*balance-(bs,-bse, cf,-is) with-report-interval*-starting   sums of      value at     sums of values     value at     sums-balances   costs of     report       of postings        report       of-(-H)       postings     start of     before report      start of     postings-           before       sums of      start at           sums of      before-           report       all          respective         all          report-           start        postings     posting dates      postings     start-                        before                          before-                        report                          report-                        start                           start-balance    sums of      same as      sums of values     balance      value-changes    costs of     -value=end   of postings in     change in    at-(bal,      postings                  period at          each         DATE/today-is, bs     in period                 respective         period,      of--change,                             posting dates      valued at    sums-cf                                                      period       of--change)                                                ends         postings-end        sums of      same as      sums of values     period end   value-balances   costs of     -value=end   of postings from   balances,    at-(bal -H,   postings                  before period      valued at    DATE/today-is -H,     from                      start to period    period       of-bs, cf)    before                    end at             ends         sums-           report                    respective                      of-           start to                  posting dates                   postings-           period end-budget     like         like         like balance       like         like-amounts    balance      balance      changes/end        balances     balance-(-budget)  changes/end  changes/end  balances                        changes/end-           balances     balances                                     balances-row        sums,        sums,        sums, averages     sums,        sums,-totals,    averages     averages     of displayed       averages     averages-row        of           of           values             of           of-averages   displayed    displayed                       displayed    displayed-(-T, -A)   values       values                          values       values-column     sums of      sums of      sums of            sums of      sums-totals     displayed    displayed    displayed values   displayed    of-           values       values                          values       displayed-                                                                     values-grand      sum,         sum,         sum, average of    sum,         sum,-total,     average of   average of   column totals      average of   average-grand      column       column                          column       of-average    totals       totals                          totals       column-                                                                     totals--   '--cumulative' is omitted to save space, it works like '-H' but with-a zero starting balance.--   *Glossary:*--_cost_--     calculated using price(s) recorded in the transaction(s).-_value_--     market value using available market price declarations, or the-     unchanged amount if no conversion rate can be found.-_report start_--     the first day of the report period specified with -b or -p or-     date:, otherwise today.-_report or journal start_--     the first day of the report period specified with -b or -p or-     date:, otherwise the earliest transaction date in the journal,-     otherwise today.-_report end_--     the last day of the report period specified with -e or -p or date:,-     otherwise today.-_report or journal end_--     the last day of the report period specified with -e or -p or date:,-     otherwise the latest transaction date in the journal, otherwise-     today.-_report interval_--     a flag (-D/-W/-M/-Q/-Y) or period expression that activates the-     report's multi-period mode (whether showing one or many-     subperiods).---File: hledger.info,  Node: PIVOTING,  Next: OUTPUT,  Prev: VALUATION,  Up: Top--9 PIVOTING-**********--Normally hledger sums amounts, and organizes them in a hierarchy, based-on account name.  The '--pivot FIELD' option causes it to sum and-organize hierarchy based on the value of some other field instead.-FIELD can be: 'code', 'description', 'payee', 'note', or the full name-(case insensitive) of any tag.  As with account names, values containing-'colon:separated:parts' will be displayed hierarchically in reports.--   '--pivot' is a general option affecting all reports; you can think of-hledger transforming the journal before any other processing, replacing-every posting's account name with the value of the specified field on-that posting, inheriting it from the transaction or using a blank value-if it's not present.--   An example:--2016/02/16 Member Fee Payment-    assets:bank account                    2 EUR-    income:member fees                    -2 EUR  ; member: John Doe--   Normal balance report showing account names:--$ hledger balance-               2 EUR  assets:bank account-              -2 EUR  income:member fees----------------------                   0--   Pivoted balance report, using member: tag values instead:--$ hledger balance --pivot member-               2 EUR-              -2 EUR  John Doe----------------------                   0--   One way to show only amounts with a member: value (using a query,-described below):--$ hledger balance --pivot member tag:member=.-              -2 EUR  John Doe----------------------              -2 EUR--   Another way (the acct: query matches against the pivoted "account-name"):--$ hledger balance --pivot member acct:.-              -2 EUR  John Doe----------------------              -2 EUR---File: hledger.info,  Node: OUTPUT,  Next: COMMANDS,  Prev: PIVOTING,  Up: Top--10 OUTPUT-*********--* Menu:--* Output destination::-* Output styling::-* Output format::-* Commodity styles::---File: hledger.info,  Node: Output destination,  Next: Output styling,  Up: OUTPUT--10.1 Output destination-=======================--hledger commands send their output to the terminal by default.  You can-of course redirect this, eg into a file, using standard shell syntax:--$ hledger print > foo.txt--   Some commands (print, register, stats, the balance commands) also-provide the '-o/--output-file' option, which does the same thing without-needing the shell.  Eg:--$ hledger print -o foo.txt-$ hledger print -o -        # write to stdout (the default)--   hledger can optionally produce debug output (if enabled with-'--debug=N'); this goes to stderr, and is not affected by-'-o/--output-file'.  If you need to capture it, use shell redirects, eg:-'hledger bal --debug=3 >file 2>&1'.---File: hledger.info,  Node: Output styling,  Next: Output format,  Prev: Output destination,  Up: OUTPUT--10.2 Output styling-===================--hledger commands can produce colour output when the terminal supports-it.  This is controlled by the '--color/--colour' option: - if the-'--color/--colour' option is given a value of 'yes' or 'always' (or 'no'-or 'never'), colour will (or will not) be used; - otherwise, if the-'NO_COLOR' environment variable is set, colour will not be used; --otherwise, colour will be used if the output (terminal or file) supports-it.--   hledger commands can also use unicode box-drawing characters to-produce prettier tables and output.  This is controlled by the-'--pretty' option: - if the '--pretty' option is given a value of 'yes'-or 'always' (or 'no' or 'never'), unicode characters will (or will not)-be used; - otherwise, unicode characters will not be used.---File: hledger.info,  Node: Output format,  Next: Commodity styles,  Prev: Output styling,  Up: OUTPUT--10.3 Output format-==================--Some commands offer additional output formats, other than the usual-plain text terminal output.  Here are those commands and the formats-currently supported:---                    txt     csv     html      json   sql--------------------------------------------------------------aregister            Y       Y                 Y-balance              Y _1_   Y _1_   Y _1,2_   Y-balancesheet         Y _1_   Y _1_   Y _1_     Y-balancesheetequity   Y _1_   Y _1_   Y _1_     Y-cashflow             Y _1_   Y _1_   Y _1_     Y-incomestatement      Y _1_   Y _1_   Y _1_     Y-print                Y       Y                 Y      Y-register             Y       Y                 Y--   * _1 Also affected by the balance commands' '--layout' option._-   * _2 'balance' does not support html output without a report interval-     or with '--budget'._--   The output format is selected by the '-O/--output-format=FMT' option:--$ hledger print -O csv    # print CSV on stdout--   or by the filename extension of an output file specified with the-'-o/--output-file=FILE.FMT' option:--$ hledger balancesheet -o foo.csv    # write CSV to foo.csv--   The '-O' option can be combined with '-o' to override the file-extension, if needed:--$ hledger balancesheet -o foo.txt -O csv    # write CSV to foo.txt--* Menu:--* CSV output::-* HTML output::-* JSON output::-* SQL output::---File: hledger.info,  Node: CSV output,  Next: HTML output,  Up: Output format--10.3.1 CSV output--------------------   * In CSV output, digit group marks (such as thousands separators) are-     disabled automatically.---File: hledger.info,  Node: HTML output,  Next: JSON output,  Prev: CSV output,  Up: Output format--10.3.2 HTML output---------------------   * HTML output can be styled by an optional 'hledger.css' file in the-     same directory.---File: hledger.info,  Node: JSON output,  Next: SQL output,  Prev: HTML output,  Up: Output format--10.3.3 JSON output---------------------   * Not yet much used; real-world feedback is welcome.--   * Our JSON is rather large and verbose, as it is quite a faithful-     representation of hledger's internal data types.  To understand the-     JSON, read the Haskell type definitions, which are mostly in-     https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs.--   * hledger represents quantities as Decimal values storing up to 255-     significant digits, eg for repeating decimals.  Such numbers can-     arise in practice (from automatically-calculated transaction-     prices), and would break most JSON consumers.  So in JSON, we show-     quantities as simple Numbers with at most 10 decimal places.  We-     don't limit the number of integer digits, but that part is under-     your control.  We hope this approach will not cause problems in-     practice; if you find otherwise, please let us know.  (Cf #1195)---File: hledger.info,  Node: SQL output,  Prev: JSON output,  Up: Output format--10.3.4 SQL output--------------------   * Not yet much used; real-world feedback is welcome.--   * SQL output is expected to work with sqlite, MySQL and PostgreSQL--   * SQL output is structured with the expectations that statements will-     be executed in the empty database.  If you already have tables-     created via SQL output of hledger, you would probably want to-     either clear tables of existing data (via 'delete' or 'truncate'-     SQL statements) or drop tables completely as otherwise your-     postings will be duped.---File: hledger.info,  Node: Commodity styles,  Prev: Output format,  Up: OUTPUT--10.4 Commodity styles-=====================--The display style of a commodity/currency is inferred according to the-rules described in Commodity display style.  The inferred display style-can be overridden by an optional '-c/--commodity-style' option-(Exceptions: as is the case for inferred styles, price amounts, and all-amounts displayed by the 'print' command, will be displayed with all of-their decimal digits visible, regardless of the specified precision).-For example, the following will override the display style for dollars.--$ hledger print -c '$1.000,0'--   The format specification of the style is identical to the commodity-display style specification for the commodity directive.  The command-line option can be supplied repeatedly to override the display style for-multiple commodity/currency symbols.---File: hledger.info,  Node: COMMANDS,  Next: JOURNAL FORMAT,  Prev: OUTPUT,  Up: Top--11 COMMANDS-***********--hledger provides a number of commands for producing reports and managing-your data.  Run 'hledger' with no arguments to list the commands-available, and 'hledger CMD' to run a command.  CMD can be the full-command name, or its standard abbreviation shown in the commands list,-or any unambiguous prefix of the name.  Eg: 'hledger bal'.--   Here are the built-in commands, with the most often-used in bold:--   *Data entry:*--   These data entry commands are the only ones which can modify your-journal file.--   * *add* - add transactions using guided prompts-   * *import* - add any new transactions from other files (eg csv)--   *Data management:*--   * check - check for various kinds of issue in the data-   * close (equity) - generate balance-resetting transactions-   * diff - compare account transactions in two journal files-   * rewrite - generate extra postings, similar to print -auto--   *Financial statements:*--   * *aregister (areg)* - show transactions in a particular account-   * *balancesheet (bs)* - show assets, liabilities and net worth-   * balancesheetequity (bse) - show assets, liabilities and equity-   * cashflow (cf) - show changes in liquid assets-   * *incomestatement (is)* - show revenues and expenses-   * roi - show return on investments--   *Miscellaneous reports:*--   * accounts - show account names-   * activity - show postings-per-interval bar charts-   * *balance (bal)* - show balance changes/end balances/budgets in any-     accounts-   * codes - show transaction codes-   * commodities - show commodity/currency symbols-   * descriptions - show unique transaction descriptions-   * files - show input file paths-   * help - show hledger user manuals in several formats-   * notes - show unique note segments of transaction descriptions-   * payees - show unique payee segments of transaction descriptions-   * prices - show market price records-   * *print* - show transactions (journal entries)-   * print-unique - show only transactions with unique descriptions-   * *register (reg)* - show postings in one or more accounts & running-     total-   * register-match - show a recent posting that best matches a-     description-   * stats - show journal statistics-   * tags - show tag names-   * test - run self tests--   *Add-on commands:*--   Programs or scripts named 'hledger-SOMETHING' in your PATH are add-on-commands; these appear in the commands list with a '+' mark.  Two of-these are maintained and released with hledger:--   * *ui* - an efficient terminal interface (TUI) for hledger-   * *web* - a simple web interface (WUI) for hledger--   And these add-ons are maintained separately:--   * iadd - a more interactive alternative for the add command-   * interest - generates interest transactions according to various-     schemes-   * stockquotes - downloads market prices for your commodities from-     AlphaVantage _(experimental)_--   Next, the detailed command docs, in alphabetical order.--* Menu:--* accounts::-* activity::-* add::-* aregister::-* balance::-* balancesheet::-* balancesheetequity::-* cashflow::-* check::-* close::-* codes::-* commodities::-* descriptions::-* diff::-* files::-* help::-* import::-* incomestatement::-* notes::-* payees::-* prices::-* print::-* print-unique::-* register::-* register-match::-* rewrite::-* roi::-* stats::-* tags::-* test::-* About add-on commands::---File: hledger.info,  Node: accounts,  Next: activity,  Up: COMMANDS--11.1 accounts-=============--accounts-Show account names.--   This command lists account names, either declared with account-directives (-declared), posted to (-used), or both (the default).  With-query arguments, only matched account names and account names referenced-by matched postings are shown.  It shows a flat list by default.  With-'--tree', it uses indentation to show the account hierarchy.  In flat-mode you can add '--drop N' to omit the first few account name-components.  Account names can be depth-clipped with 'depth:N' or-'--depth N' or '-N'.--   Examples:--$ hledger accounts-assets:bank:checking-assets:bank:saving-assets:cash-expenses:food-expenses:supplies-income:gifts-income:salary-liabilities:debts---File: hledger.info,  Node: activity,  Next: add,  Prev: accounts,  Up: COMMANDS--11.2 activity-=============--activity-Show an ascii barchart of posting counts per interval.--   The activity command displays an ascii histogram showing transaction-counts by day, week, month or other reporting interval (by day is the-default).  With query arguments, it counts only matched transactions.--   Examples:--$ hledger activity --quarterly-2008-01-01 **-2008-04-01 *******-2008-07-01 -2008-10-01 **---File: hledger.info,  Node: add,  Next: aregister,  Prev: activity,  Up: COMMANDS--11.3 add-========--add-Prompt for transactions and add them to the journal.  Any arguments will-be used as default inputs for the first N prompts.--   Many hledger users edit their journals directly with a text editor,-or generate them from CSV. For more interactive data entry, there is the-'add' command, which prompts interactively on the console for new-transactions, and appends them to the journal file (if there are-multiple '-f FILE' options, the first file is used.)  Existing-transactions are not changed.  This is the only hledger command that-writes to the journal file.--   To use it, just run 'hledger add' and follow the prompts.  You can-add as many transactions as you like; when you are finished, enter '.'-or press control-d or control-c to exit.--   Features:--   * add tries to provide useful defaults, using the most similar (by-     description) recent transaction (filtered by the query, if any) as-     a template.-   * You can also set the initial defaults with command line arguments.-   * Readline-style edit keys can be used during data entry.-   * The tab key will auto-complete whenever possible - accounts,-     descriptions, dates ('yesterday', 'today', 'tomorrow').  If the-     input area is empty, it will insert the default value.-   * If the journal defines a default commodity, it will be added to any-     bare numbers entered.-   * A parenthesised transaction code may be entered following a date.-   * Comments and tags may be entered following a description or amount.-   * If you make a mistake, enter '<' at any prompt to go one step-     backward.-   * Input prompts are displayed in a different colour when the terminal-     supports it.--   Example (see the tutorial for a detailed explanation):--$ hledger add-Adding transactions to journal file /src/hledger/examples/sample.journal-Any command line arguments will be used as defaults.-Use tab key to complete, readline keys to edit, enter to accept defaults.-An optional (CODE) may follow transaction dates.-An optional ; COMMENT may follow descriptions or amounts.-If you make a mistake, enter < at any prompt to go one step backward.-To end a transaction, enter . when prompted.-To quit, enter . at a date prompt or press control-d or control-c.-Date [2015/05/22]: -Description: supermarket-Account 1: expenses:food-Amount  1: $10-Account 2: assets:checking-Amount  2 [$-10.0]: -Account 3 (or . or enter to finish this transaction): .-2015/05/22 supermarket-    expenses:food             $10-    assets:checking        $-10.0--Save this transaction to the journal ? [y]: -Saved.-Starting the next transaction (. or ctrl-D/ctrl-C to quit)-Date [2015/05/22]: <CTRL-D> $--   On Microsoft Windows, the add command makes sure that no part of the-file path ends with a period, as that would cause problems (#1056).---File: hledger.info,  Node: aregister,  Next: balance,  Prev: add,  Up: COMMANDS--11.4 aregister-==============--aregister, areg--   Show the transactions and running historical balance of a single-account, with each transaction displayed as one line.--   'aregister' shows the overall transactions affecting a particular-account (and any subaccounts).  Each report line represents one-transaction in this account.  Transactions before the report start date-are always included in the running balance ('--historical' mode is-always on).--   This is a more "real world", bank-like view than the 'register'-command (which shows individual postings, possibly from multiple-accounts, not necessarily in historical mode).  As a quick rule of-thumb: - use 'aregister' for reviewing and reconciling real-world-asset/liability accounts - use 'register' for reviewing detailed-revenues/expenses.--   'aregister' requires one argument: the account to report on.  You can-write either the full account name, or a case-insensitive regular-expression which will select the alphabetically first matched account.-(Eg if you have 'assets:aaa:checking' and 'assets:bbb:checking'-accounts, 'hledger areg checking' would select 'assets:aaa:checking'.)--   Transactions involving subaccounts of this account will also be-shown.  'aregister' ignores depth limits, so its final total will always-match a balance report with similar arguments.--   Any additional arguments form a query which will filter the-transactions shown.  Note some queries will disturb the running balance,-causing it to be different from the account's real-world running-balance.--   An example: this shows the transactions and historical running-balance during july, in the first account whose name contains-"checking":--$ hledger areg checking date:jul--   Each 'aregister' line item shows:--   * the transaction's date (or the relevant posting's date if-     different, see below)-   * the names of all the other account(s) involved in this transaction-     (probably abbreviated)-   * the total change to this account's balance from this transaction-   * the account's historical running balance after this transaction.--   Transactions making a net change of zero are not shown by default;-add the '-E/--empty' flag to show them.--   This command also supports the output destination and output format-options.  The output formats supported are 'txt', 'csv', and 'json'.--* Menu:--* aregister and custom posting dates::---File: hledger.info,  Node: aregister and custom posting dates,  Up: aregister--11.4.1 aregister and custom posting dates--------------------------------------------Transactions whose date is outside the report period can still be shown,-if they have a posting to this account dated inside the report period.-(And in this case it's the posting date that is shown.)  This ensures-that 'aregister' can show an accurate historical running balance,-matching the one shown by 'register -H' with the same arguments.--   To filter strictly by transaction date instead, add the '--txn-dates'-flag.  If you use this flag and some of your postings have custom dates,-it's probably best to assume the running balance is wrong.---File: hledger.info,  Node: balance,  Next: balancesheet,  Prev: aregister,  Up: COMMANDS--11.5 balance-============--balance, bal-Show accounts and their balances.--   'balance' is one of hledger's oldest and most versatile commands, for-listing account balances, balance changes, values, value changes and-more, during one time period or many.  Generally it shows a table, with-rows representing accounts, and columns representing periods.--   Note there are some higher-level variants of the 'balance' command-with convenient defaults, which can be simpler to use: 'balancesheet',-'balancesheetequity', 'cashflow' and 'incomestatement'.  When you need-more control, then use 'balance'.--* Menu:--* balance features::-* Simple balance report::-* Filtered balance report::-* List or tree mode::-* Depth limiting::-* Dropping top-level accounts::-* Multi-period balance report::-* Showing declared accounts::-* Data layout::-* Sorting by amount::-* Percentages::-* Balance change end balance::-* Balance report types::-* Useful balance reports::-* Budget report::-* Customising single-period balance reports::---File: hledger.info,  Node: balance features,  Next: Simple balance report,  Up: balance--11.5.1 balance features--------------------------Here's a quick overview of the 'balance' command's features, followed by-more detailed descriptions and examples.  Many of these work with the-higher-level commands as well.--   'balance' can show..--   * accounts as a list ('-l') or a tree ('-t')-   * optionally depth-limited ('-[1-9]')-   * sorted by declaration order and name, or by amount--   ..and their..--   * balance changes (the default)-   * or actual and planned balance changes ('--budget')-   * or value of balance changes ('-V')-   * or change of balance values ('--valuechange')-   * or unrealised capital gain/loss ('--gain')--   ..in..--   * one time period (the whole journal period by default)-   * or multiple periods ('-D', '-W', '-M', '-Q', '-Y', '-p INTERVAL')--   ..either..--   * per period (the default)-   * or accumulated since report start date ('--cumulative')-   * or accumulated since account creation ('--historical/-H')--   ..possibly converted to..--   * cost ('--value=cost[,COMM]'/'--cost'/'-B')-   * or market value, as of transaction dates ('--value=then[,COMM]')-   * or at period ends ('--value=end[,COMM]')-   * or now ('--value=now')-   * or at some other date ('--value=YYYY-MM-DD')--   ..with..--   * totals ('-T'), averages ('-A'), percentages ('-%'), inverted sign-     ('--invert')-   * rows and columns swapped ('--transpose')-   * another field used as account name ('--pivot')-   * custom-formatted line items (single-period reports only)-     ('--format')-   * commodities displayed on the same line or multiple lines-     ('--layout')--   This command supports the output destination and output format-options, with output formats 'txt', 'csv', 'json', and (multi-period-reports only:) 'html'.  In 'txt' output in a colour-supporting terminal,-negative amounts are shown in red.--   The '--related'/'-r' flag shows the balance of the _other_ postings-in the transactions of the postings which would normally be shown.---File: hledger.info,  Node: Simple balance report,  Next: Filtered balance report,  Prev: balance features,  Up: balance--11.5.2 Simple balance report-------------------------------With no arguments, 'balance' shows a list of all accounts and their-change of balance - ie, the sum of posting amounts, both inflows and-outflows - during the entire period of the journal.  For real-world-accounts, this should also match their end balance at the end of the-journal period (more on this below).--   Accounts are sorted by declaration order if any, and then-alphabetically by account name.  For instance (using-examples/sample.journal):--$ hledger -f examples/sample.journal bal-                  $1  assets:bank:saving-                 $-2  assets:cash-                  $1  expenses:food-                  $1  expenses:supplies-                 $-1  income:gifts-                 $-1  income:salary-                  $1  liabilities:debts----------------------                   0  --   Accounts with a zero balance (and no non-zero subaccounts, in tree-mode - see below) are hidden by default.  Use '-E/--empty' to show them-(revealing 'assets:bank:checking' here):--$ hledger -f examples/sample.journal bal  -E-                   0  assets:bank:checking-                  $1  assets:bank:saving-                 $-2  assets:cash-                  $1  expenses:food-                  $1  expenses:supplies-                 $-1  income:gifts-                 $-1  income:salary-                  $1  liabilities:debts----------------------                   0  --   The total of the amounts displayed is shown as the last line, unless-'-N'/'--no-total' is used.---File: hledger.info,  Node: Filtered balance report,  Next: List or tree mode,  Prev: Simple balance report,  Up: balance--11.5.3 Filtered balance report---------------------------------You can show fewer accounts, a different time period, totals from-cleared transactions only, etc.  by using query arguments or options to-limit the postings being matched.  Eg:--$ hledger -f examples/sample.journal bal --cleared assets date:200806-                 $-2  assets:cash----------------------                 $-2  ---File: hledger.info,  Node: List or tree mode,  Next: Depth limiting,  Prev: Filtered balance report,  Up: balance--11.5.4 List or tree mode---------------------------By default, or with '-l/--flat', accounts are shown as a flat list with-their full names visible, as in the examples above.--   With '-t/--tree', the account hierarchy is shown, with subaccounts'-"leaf" names indented below their parent:--$ hledger -f examples/sample.journal balance-                 $-1  assets-                  $1    bank:saving-                 $-2    cash-                  $2  expenses-                  $1    food-                  $1    supplies-                 $-2  income-                 $-1    gifts-                 $-1    salary-                  $1  liabilities:debts----------------------                   0--   Notes:--   * "Boring" accounts are combined with their subaccount for more-     compact output, unless '--no-elide' is used.  Boring accounts have-     no balance of their own and just one subaccount (eg 'assets:bank'-     and 'liabilities' above).--   * All balances shown are "inclusive", ie including the balances from-     all subaccounts.  Note this means some repetition in the output,-     which requires explanation when sharing reports with-     non-plaintextaccounting-users.  A tree mode report's final total is-     the sum of the top-level balances shown, not of all the balances-     shown.--   * Each group of sibling accounts (ie, under a common parent) is-     sorted separately.---File: hledger.info,  Node: Depth limiting,  Next: Dropping top-level accounts,  Prev: List or tree mode,  Up: balance--11.5.5 Depth limiting------------------------With a 'depth:NUM' query, or '--depth NUM' option, or just '-NUM' (eg:-'-3') balance reports will show accounts only to the specified depth,-hiding the deeper subaccounts.  This can be useful for getting an-overview without too much detail.--   Account balances at the depth limit always include the balances from-any deeper subaccounts (even in list mode).  Eg, limiting to depth 1:--$ hledger -f examples/sample.journal balance -1-                 $-1  assets-                  $2  expenses-                 $-2  income-                  $1  liabilities----------------------                   0  ---File: hledger.info,  Node: Dropping top-level accounts,  Next: Multi-period balance report,  Prev: Depth limiting,  Up: balance--11.5.6 Dropping top-level accounts-------------------------------------You can also hide one or more top-level account name parts, using-'--drop NUM'.  This can be useful for hiding repetitive top-level-account names:--$ hledger -f examples/sample.journal bal expenses --drop 1-                  $1  food-                  $1  supplies----------------------                  $2  ---File: hledger.info,  Node: Multi-period balance report,  Next: Showing declared accounts,  Prev: Dropping top-level accounts,  Up: balance--11.5.7 Multi-period balance report-------------------------------------With a report interval (set by the '-D/--daily', '-W/--weekly',-'-M/--monthly', '-Q/--quarterly', '-Y/--yearly', or '-p/--period' flag),-'balance' shows a tabular report, with columns representing successive-time periods (and a title):--$ hledger -f examples/sample.journal bal --quarterly income expenses -E-Balance changes in 2008:--                   ||  2008q1  2008q2  2008q3  2008q4 -===================++=================================- expenses:food     ||       0      $1       0       0 - expenses:supplies ||       0      $1       0       0 - income:gifts      ||       0     $-1       0       0 - income:salary     ||     $-1       0       0       0 --------------------++----------------------------------                   ||     $-1      $1       0       0 --   Notes:--   * The report's start/end dates will be expanded, if necessary, to-     fully encompass the displayed subperiods (so that the first and-     last subperiods have the same duration as the others).-   * Leading and trailing periods (columns) containing all zeroes are-     not shown, unless '-E/--empty' is used.-   * Accounts (rows) containing all zeroes are not shown, unless-     '-E/--empty' is used.-   * Amounts with many commodities are shown in abbreviated form, unless-     '--no-elide' is used.  _(experimental)_-   * Average and/or total columns can be added with the '-A/--average'-     and '-T/--row-total' flags.-   * The '--transpose' flag can be used to exchange rows and columns.-   * The '--pivot FIELD' option causes a different transaction field to-     be used as "account name".  See PIVOTING.--   Multi-period reports with many periods can be too wide for easy-viewing in the terminal.  Here are some ways to handle that:--   * Hide the totals row with '-N/--no-total'-   * Convert to a single currency with '-V'-   * Maximize the terminal window-   * Reduce the terminal's font size-   * View with a pager like less, eg: 'hledger bal -D --color=yes | less-     -RS'-   * Output as CSV and use a CSV viewer like visidata ('hledger bal -D-     -O csv | vd -f csv'), Emacs' csv-mode ('M-x csv-mode, C-c C-a'), or-     a spreadsheet ('hledger bal -D -o a.csv && open a.csv')-   * Output as HTML and view with a browser: 'hledger bal -D -o a.html-     && open a.html'---File: hledger.info,  Node: Showing declared accounts,  Next: Data layout,  Prev: Multi-period balance report,  Up: balance--11.5.8 Showing declared accounts-----------------------------------With '--declared', accounts which have been declared with an account-directive will be included in the balance report, even if they have no-transactions.  (Since they will have a zero balance, you will also need-'-E/--empty' to see them.)--   More precisely, _leaf_ declared accounts (with no subaccounts) will-be included, since those are usually the more useful in reports.--   The idea of this is to be able to see a useful "complete" balance-report, even when you don't have transactions in all of your declared-accounts yet.---File: hledger.info,  Node: Data layout,  Next: Sorting by amount,  Prev: Showing declared accounts,  Up: balance--11.5.9 Data layout---------------------The '--layout' option affects how multi-commodity amounts are displayed,-and some other things, influencing the overall layout of the report-data:--   * '--layout=wide[,WIDTH]': commodities are shown on a single line,-     possibly elided to the specified width-   * '--layout=tall': each commodity is shown on a separate line-   * '--layout=bare': amounts are shown as bare numbers, with commodity-     symbols in a separate column-   * '--layout=tidy': data is normalised to tidy form, with one row per-     data value.  We currently support this with CSV output only.  In-     tidy mode, totals and row averages are disabled ('-N/--no-total' is-     implied and '-T/--row-total' and '-A/--average' will be ignored).--   These '--layout' modes are supported with some but not all of the-output formats:---      txt   csv   html   json   sql-----------------------------------------wide   Y     Y     Y-tall   Y     Y     Y-bare   Y     Y     Y-tidy         Y--   Examples:--   * Wide layout.  With many commodities, reports can be very wide:--     $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide-     Balance changes in 2012-01-01..2014-12-31:-     -                       ||                                          2012                                                     2013                                             2014                                                      Total -     ==================++====================================================================================================================================================================================================================-      Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT  70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT  -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT  70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT -     ------------------++---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------                       || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT  70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT  -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT  70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT --   * Limited wide layout.  A width limit reduces the width, but some-     commodities will be hidden:--     $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32-     Balance changes in 2012-01-01..2014-12-31:-     -                       ||                             2012                             2013                   2014                            Total -     ==================++===========================================================================================================================-      Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more..  70.00 GLD, 18.00 ITOT, 3 more..  -11.00 ITOT, 3 more..  70.00 GLD, 17.00 ITOT, 3 more.. -     ------------------++----------------------------------------------------------------------------------------------------------------------------                       || 10.00 ITOT, 337.18 USD, 2 more..  70.00 GLD, 18.00 ITOT, 3 more..  -11.00 ITOT, 3 more..  70.00 GLD, 17.00 ITOT, 3 more.. --   * Tall layout.  Each commodity gets a new line (may be different in-     each column), and account names are repeated:--     $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall-     Balance changes in 2012-01-01..2014-12-31:-     -                       ||       2012        2013         2014        Total -     ==================++==================================================-      Assets:US:ETrade || 10.00 ITOT   70.00 GLD  -11.00 ITOT    70.00 GLD -      Assets:US:ETrade || 337.18 USD  18.00 ITOT  4881.44 USD   17.00 ITOT -      Assets:US:ETrade ||  12.00 VEA  -98.12 USD    14.00 VEA  5120.50 USD -      Assets:US:ETrade || 106.00 VHT   10.00 VEA   170.00 VHT    36.00 VEA -      Assets:US:ETrade ||              18.00 VHT                294.00 VHT -     ------------------++---------------------------------------------------                       || 10.00 ITOT   70.00 GLD  -11.00 ITOT    70.00 GLD -                       || 337.18 USD  18.00 ITOT  4881.44 USD   17.00 ITOT -                       ||  12.00 VEA  -98.12 USD    14.00 VEA  5120.50 USD -                       || 106.00 VHT   10.00 VEA   170.00 VHT    36.00 VEA -                       ||              18.00 VHT                294.00 VHT --   * Bare layout.  Commodity symbols are kept in one column, each-     commodity gets its own report row, account names are repeated:--     $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare-     Balance changes in 2012-01-01..2014-12-31:-     -                       || Commodity    2012    2013     2014    Total -     ==================++=============================================-      Assets:US:ETrade || GLD             0   70.00        0    70.00 -      Assets:US:ETrade || ITOT        10.00   18.00   -11.00    17.00 -      Assets:US:ETrade || USD        337.18  -98.12  4881.44  5120.50 -      Assets:US:ETrade || VEA         12.00   10.00    14.00    36.00 -      Assets:US:ETrade || VHT        106.00   18.00   170.00   294.00 -     ------------------++----------------------------------------------                       || GLD             0   70.00        0    70.00 -                       || ITOT        10.00   18.00   -11.00    17.00 -                       || USD        337.18  -98.12  4881.44  5120.50 -                       || VEA         12.00   10.00    14.00    36.00 -                       || VHT        106.00   18.00   170.00   294.00 --   * Bare layout also affects CSV output, which is useful for producing-     data that is easier to consume, eg when making charts:--     $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare-     "account","commodity","balance"-     "Assets:US:ETrade","GLD","70.00"-     "Assets:US:ETrade","ITOT","17.00"-     "Assets:US:ETrade","USD","5120.50"-     "Assets:US:ETrade","VEA","36.00"-     "Assets:US:ETrade","VHT","294.00"-     "total","GLD","70.00"-     "total","ITOT","17.00"-     "total","USD","5120.50"-     "total","VEA","36.00"-     "total","VHT","294.00"--   * Tidy layout produces normalised "tidy data", where every variable-     is a column and each row represents a single data point (see-     https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html).-     This kind of data is the easiest to process with other software:--     $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy-     "account","period","start_date","end_date","commodity","value"-     "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0"-     "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00"-     "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18"-     "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00"-     "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00"-     "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00"-     "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00"-     "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12"-     "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00"-     "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00"-     "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0"-     "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00"-     "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44"-     "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00"-     "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00"---File: hledger.info,  Node: Sorting by amount,  Next: Percentages,  Prev: Data layout,  Up: balance--11.5.10 Sorting by amount----------------------------With '-S/--sort-amount', accounts with the largest (most positive)-balances are shown first.  Eg: 'hledger bal expenses -MAS' shows your-biggest averaged monthly expenses first.  When more than one commodity-is present, they will be sorted by the alphabetically earliest commodity-first, and then by subsequent commodities (if an amount is missing a-commodity, it is treated as 0).--   Revenues and liability balances are typically negative, however, so-'-S' shows these in reverse order.  To work around this, you can add-'--invert' to flip the signs.  (Or, use one of the higher-level reports,-which flip the sign automatically.  Eg: 'hledger incomestatement -MAS').---File: hledger.info,  Node: Percentages,  Next: Balance change end balance,  Prev: Sorting by amount,  Up: balance--11.5.11 Percentages----------------------With '-%/--percent', balance reports show each account's value expressed-as a percentage of the (column) total:--$ hledger -f examples/sample.journal bal expenses -Q -%-Balance changes in 2008:--                   || 2008Q1   2008Q2  2008Q3  2008Q4 -===================++=================================- expenses:food     ||      0   50.0 %       0       0 - expenses:supplies ||      0   50.0 %       0       0 --------------------++----------------------------------                   ||      0  100.0 %       0       0 --   Note it is not useful to calculate percentages if the amounts in a-column have mixed signs.  In this case, make a separate report for each-sign, eg:--$ hledger bal -% amt:`>0`-$ hledger bal -% amt:`<0`--   Similarly, if the amounts in a column have mixed commodities, convert-them to one commodity with '-B', '-V', '-X' or '--value', or make a-separate report for each commodity:--$ hledger bal -% cur:\\$-$ hledger bal -% cur:€---File: hledger.info,  Node: Balance change end balance,  Next: Balance report types,  Prev: Percentages,  Up: balance--11.5.12 Balance change, end balance--------------------------------------It's important to be clear on the meaning of the numbers shown in-balance reports.  Here is some terminology we use:--   A *_balance change_* is the net amount added to, or removed from, an-account during some period.--   An *_end balance_* is the amount accumulated in an account as of some-date (and some time, but hledger doesn't store that; assume end of day-in your timezone).  It is the sum of previous balance changes.--   We call it a *_historical end balance_* if it includes all balance-changes since the account was created.  For a real world account, this-means it will match the "historical record", eg the balances reported in-your bank statements or bank web UI. (If they are correct!)--   In general, balance changes are what you want to see when reviewing-revenues and expenses, and historical end balances are what you want to-see when reviewing or reconciling asset, liability and equity accounts.--   'balance' shows balance changes by default.  To see accurate-historical end balances:--  1. Initialise account starting balances with an "opening balances"-     transaction (a transfer from equity to the account), unless the-     journal covers the account's full lifetime.--  2. Include all of of the account's prior postings in the report, by-     not specifying a report start date, or by using the-     '-H/--historical' flag.  ('-H' causes report start date to be-     ignored when summing postings.)---File: hledger.info,  Node: Balance report types,  Next: Useful balance reports,  Prev: Balance change end balance,  Up: balance--11.5.13 Balance report types-------------------------------For more flexible reporting, there are three important option groups:--   'hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE]-...'--   The first two are the most important: calculation type selects the-basic calculation to perform for each table cell, while accumulation-type says which postings should be included in each cell's calculation.-Typically one or both of these are selected by default, so you don't-need to write them explicitly.  A valuation type can be added if you-want to convert the basic report to value or cost.--   *Calculation type:*-The basic calculation to perform for each table cell.  It is one of:--   * '--sum' : sum the posting amounts (*default*)-   * '--budget' : like -sum but also show a goal amount-   * '--valuechange' : show the change in period-end historical balance-     values (caused by deposits, withdrawals, and/or market price-     fluctuations)-   * '--gain' : show the unrealised capital gain/loss, (the current-     valued balance minus each amount's original cost)--   *Accumulation type:*-Which postings should be included in each cell's calculation.  It is one-of:--   * '--change' : postings from column start to column end, ie within-     the cell's period.  Typically used to see revenues/expenses.-     (*default for balance, incomestatement*)--   * '--cumulative' : postings from report start to column end, eg to-     show changes accumulated since the report's start date.  Rarely-     used.--   * '--historical/-H' : postings from journal start to column end, ie-     all postings from account creation to the end of the cell's period.-     Typically used to see historical end balances of-     assets/liabilities/equity.  (*default for balancesheet,-     balancesheetequity, cashflow*)--   *Valuation type:*-Which kind of valuation, valuation date(s) and optionally a target-valuation commodity to use.  It is one of:--   * no valuation, show amounts in their original commodities-     (*default*)-   * '--value=cost[,COMM]' : no valuation, show amounts converted to-     cost-   * '--value=then[,COMM]' : show value at transaction dates-   * '--value=end[,COMM]' : show value at period end date(s) (*default-     with '--valuechange', '--gain'*)-   * '--value=now[,COMM]' : show value at today's date-   * '--value=YYYY-MM-DD[,COMM]' : show value at another date--   or one of their aliases: '--cost/-B', '--market/-V' or-'--exchange/-X'.--   Most combinations of these options should produce reasonable reports,-but if you find any that seem wrong or misleading, let us know.  The-following restrictions are applied:--   * '--valuechange' implies '--value=end'-   * '--valuechange' makes '--change' the default when used with the-     'balancesheet'/'balancesheetequity' commands-   * '--cumulative' or '--historical' disables '--row-total/-T'--   For reference, here is what the combinations of accumulation and-valuation show:--Valuation:no valuation      '--value= then'   '--value= end'   '--value=->Accumulation:                                                 YYYY-MM-DD-v                                                              /now'--------------------------------------------------------------------------------'--change'change in         sum of            period-end       DATE-value-          period            posting-date      value of         of change in-                            market values     change in        period-                            in period         period-'--cumulative'change from   sum of            period-end       DATE-value-          report start to   posting-date      value of         of change-          period end        market values     change from      from report-                            from report       report start     start to-                            start to period   to period end    period end-                            end-'--historicalchange from    sum of            period-end       DATE-value-/-H'      journal start     posting-date      value of         of change-          to period end     market values     change from      from journal-          (historical end   from journal      journal start    start to-          balance)          start to period   to period end    period end-                            end---File: hledger.info,  Node: Useful balance reports,  Next: Budget report,  Prev: Balance report types,  Up: balance--11.5.14 Useful balance reports---------------------------------Some frequently used 'balance' options/reports are:--   * 'bal -M revenues expenses'-     Show revenues/expenses in each month.  Also available as the-     'incomestatement' command.--   * 'bal -M -H assets liabilities'-     Show historical asset/liability balances at each month end.  Also-     available as the 'balancesheet' command.--   * 'bal -M -H assets liabilities equity'-     Show historical asset/liability/equity balances at each month end.-     Also available as the 'balancesheetequity' command.--   * 'bal -M assets not:receivable'-     Show changes to liquid assets in each month.  Also available as the-     'cashflow' command.--   Also:--   * 'bal -M expenses -2 -SA'-     Show monthly expenses summarised to depth 2 and sorted by average-     amount.--   * 'bal -M --budget expenses'-     Show monthly expenses and budget goals.--   * 'bal -M --valuechange investments'-     Show monthly change in market value of investment assets.--   * 'bal investments --valuechange -D date:lastweek amt:'>1000' -STA-     [--invert]'-     Show top gainers [or losers] last week---File: hledger.info,  Node: Budget report,  Next: Customising single-period balance reports,  Prev: Useful balance reports,  Up: balance--11.5.15 Budget report------------------------The '--budget' report type activates extra columns showing any budget-goals for each account and period.  The budget goals are defined by-periodic transactions.  This is very useful for comparing planned and-actual income, expenses, time usage, etc.--   For example, you can take average monthly expenses in the common-expense categories to construct a minimal monthly budget:--;; Budget-~ monthly-  income  $2000-  expenses:food    $400-  expenses:bus     $50-  expenses:movies  $30-  assets:bank:checking--;; Two months worth of expenses-2017-11-01-  income  $1950-  expenses:food    $396-  expenses:bus     $49-  expenses:movies  $30-  expenses:supplies  $20-  assets:bank:checking--2017-12-01-  income  $2100-  expenses:food    $412-  expenses:bus     $53-  expenses:gifts   $100-  assets:bank:checking--   You can now see a monthly budget report:--$ hledger balance -M --budget-Budget performance in 2017/11/01-2017/12/31:--                      ||                      Nov                       Dec -======================++====================================================- assets               || $-2445 [  99% of $-2480]  $-2665 [ 107% of $-2480] - assets:bank          || $-2445 [  99% of $-2480]  $-2665 [ 107% of $-2480] - assets:bank:checking || $-2445 [  99% of $-2480]  $-2665 [ 107% of $-2480] - expenses             ||   $495 [ 103% of   $480]    $565 [ 118% of   $480] - expenses:bus         ||    $49 [  98% of    $50]     $53 [ 106% of    $50] - expenses:food        ||   $396 [  99% of   $400]    $412 [ 103% of   $400] - expenses:movies      ||    $30 [ 100% of    $30]       0 [   0% of    $30] - income               ||  $1950 [  98% of  $2000]   $2100 [ 105% of  $2000] -----------------------++-----------------------------------------------------                      ||      0 [              0]       0 [              0] --   This is different from a normal balance report in several ways:--   * Only accounts with budget goals during the report period are shown,-     by default.--   * In each column, in square brackets after the actual amount, budget-     goal amounts are shown, and the actual/goal percentage.  (Note:-     budget goals should be in the same commodity as the actual amount.)--   * All parent accounts are always shown, even in list mode.  Eg-     assets, assets:bank, and expenses above.--   * Amounts always include all subaccounts, budgeted or unbudgeted,-     even in list mode.--   This means that the numbers displayed will not always add up!  Eg-above, the 'expenses' actual amount includes the gifts and supplies-transactions, but the 'expenses:gifts' and 'expenses:supplies' accounts-are not shown, as they have no budget amounts declared.--   This can be confusing.  When you need to make things clearer, use the-'-E/--empty' flag, which will reveal all accounts including unbudgeted-ones, giving the full picture.  Eg:--$ hledger balance -M --budget --empty-Budget performance in 2017/11/01-2017/12/31:--                      ||                      Nov                       Dec -======================++====================================================- assets               || $-2445 [  99% of $-2480]  $-2665 [ 107% of $-2480] - assets:bank          || $-2445 [  99% of $-2480]  $-2665 [ 107% of $-2480] - assets:bank:checking || $-2445 [  99% of $-2480]  $-2665 [ 107% of $-2480] - expenses             ||   $495 [ 103% of   $480]    $565 [ 118% of   $480] - expenses:bus         ||    $49 [  98% of    $50]     $53 [ 106% of    $50] - expenses:food        ||   $396 [  99% of   $400]    $412 [ 103% of   $400] - expenses:gifts       ||      0                      $100                   - expenses:movies      ||    $30 [ 100% of    $30]       0 [   0% of    $30] - expenses:supplies    ||    $20                         0                   - income               ||  $1950 [  98% of  $2000]   $2100 [ 105% of  $2000] -----------------------++-----------------------------------------------------                      ||      0 [              0]       0 [              0] --   You can roll over unspent budgets to next period with '--cumulative':--$ hledger balance -M --budget --cumulative-Budget performance in 2017/11/01-2017/12/31:--                      ||                      Nov                       Dec -======================++====================================================- assets               || $-2445 [  99% of $-2480]  $-5110 [ 103% of $-4960] - assets:bank          || $-2445 [  99% of $-2480]  $-5110 [ 103% of $-4960] - assets:bank:checking || $-2445 [  99% of $-2480]  $-5110 [ 103% of $-4960] - expenses             ||   $495 [ 103% of   $480]   $1060 [ 110% of   $960] - expenses:bus         ||    $49 [  98% of    $50]    $102 [ 102% of   $100] - expenses:food        ||   $396 [  99% of   $400]    $808 [ 101% of   $800] - expenses:movies      ||    $30 [ 100% of    $30]     $30 [  50% of    $60] - income               ||  $1950 [  98% of  $2000]   $4050 [ 101% of  $4000] -----------------------++-----------------------------------------------------                      ||      0 [              0]       0 [              0] --   For more examples and notes, see Budgeting.--* Menu:--* Budget report start date::-* Budgets and subaccounts::-* Selecting budget goals::---File: hledger.info,  Node: Budget report start date,  Next: Budgets and subaccounts,  Up: Budget report--11.5.15.1 Budget report start date-..................................--This might be a bug, but for now: when making budget reports, it's a-good idea to explicitly set the report's start date to the first day of-a reporting period, because a periodic rule like '~ monthly' generates-its transactions on the 1st of each month, and if your journal has no-regular transactions on the 1st, the default report start date could-exclude that budget goal, which can be a little surprising.  Eg here the-default report period is just the day of 2020-01-15:--~ monthly in 2020-  (expenses:food)  $500--2020-01-15-  expenses:food    $400-  assets:checking--$ hledger bal expenses --budget-Budget performance in 2020-01-15:--              || 2020-01-15 -==============++============- <unbudgeted> ||       $400 ---------------++-------------              ||       $400 --   To avoid this, specify the budget report's period, or at least the-start date, with '-b'/'-e'/'-p'/'date:', to ensure it includes the-budget goal transactions (periodic transactions) that you want.  Eg,-adding '-b 2020/1/1' to the above:--$ hledger bal expenses --budget -b 2020/1/1-Budget performance in 2020-01-01..2020-01-15:--               || 2020-01-01..2020-01-15 -===============++========================- expenses:food ||     $400 [80% of $500] ----------------++-------------------------               ||     $400 [80% of $500] ---File: hledger.info,  Node: Budgets and subaccounts,  Next: Selecting budget goals,  Prev: Budget report start date,  Up: Budget report--11.5.15.2 Budgets and subaccounts-.................................--You can add budgets to any account in your account hierarchy.  If you-have budgets on both parent account and some of its children, then-budget(s) of the child account(s) would be added to the budget of their-parent, much like account balances behave.--   In the most simple case this means that once you add a budget to any-account, all its parents would have budget as well.--   To illustrate this, consider the following budget:--~ monthly from 2019/01-    expenses:personal             $1,000.00-    expenses:personal:electronics    $100.00-    liabilities--   With this, monthly budget for electronics is defined to be $100 and-budget for personal expenses is an additional $1000, which implicitly-means that budget for both 'expenses:personal' and 'expenses' is $1100.--   Transactions in 'expenses:personal:electronics' will be counted both-towards its $100 budget and $1100 of 'expenses:personal' , and-transactions in any other subaccount of 'expenses:personal' would be-counted towards only towards the budget of 'expenses:personal'.--   For example, let's consider these transactions:--~ monthly from 2019/01-    expenses:personal             $1,000.00-    expenses:personal:electronics    $100.00-    liabilities--2019/01/01 Google home hub-    expenses:personal:electronics          $90.00-    liabilities                           $-90.00--2019/01/02 Phone screen protector-    expenses:personal:electronics:upgrades          $10.00-    liabilities--2019/01/02 Weekly train ticket-    expenses:personal:train tickets       $153.00-    liabilities--2019/01/03 Flowers-    expenses:personal          $30.00-    liabilities--   As you can see, we have transactions in-'expenses:personal:electronics:upgrades' and 'expenses:personal:train-tickets', and since both of these accounts are without explicitly-defined budget, these transactions would be counted towards budgets of-'expenses:personal:electronics' and 'expenses:personal' accordingly:--$ hledger balance --budget -M-Budget performance in 2019/01:--                               ||                           Jan -===============================++===============================- expenses                      ||  $283.00 [  26% of  $1100.00] - expenses:personal             ||  $283.00 [  26% of  $1100.00] - expenses:personal:electronics ||  $100.00 [ 100% of   $100.00] - liabilities                   || $-283.00 [  26% of $-1100.00] --------------------------------++--------------------------------                               ||        0 [                 0] --   And with '--empty', we can get a better picture of budget allocation-and consumption:--$ hledger balance --budget -M --empty-Budget performance in 2019/01:--                                        ||                           Jan -========================================++===============================- expenses                               ||  $283.00 [  26% of  $1100.00] - expenses:personal                      ||  $283.00 [  26% of  $1100.00] - expenses:personal:electronics          ||  $100.00 [ 100% of   $100.00] - expenses:personal:electronics:upgrades ||   $10.00                      - expenses:personal:train tickets        ||  $153.00                      - liabilities                            || $-283.00 [  26% of $-1100.00] -----------------------------------------++--------------------------------                                        ||        0 [                 0] ---File: hledger.info,  Node: Selecting budget goals,  Prev: Budgets and subaccounts,  Up: Budget report--11.5.15.3 Selecting budget goals-................................--The budget report evaluates periodic transaction rules to generate-special "goal transactions", which generate the goal amounts for each-account in each report subperiod.  When troubleshooting, you can use the-print command to show these as forecasted transactions:--$ hledger print --forecast=BUDGETREPORTPERIOD tag:generated--   By default, the budget report uses all available periodic transaction-rules to generate goals.  This includes rules with a different report-interval from your report.  Eg if you have daily, weekly and monthly-periodic rules, all of these will contribute to the goals in a monthly-budget report.--   You can select a subset of periodic rules by providing an argument to-the '--budget' flag.  '--budget=DESCPAT' will match all periodic rules-whose description contains DESCPAT, a case-insensitive substring (not a-regular expression or query).  This means you can give your periodic-rules descriptions (remember that two spaces are needed), and then-select from multiple budgets defined in your journal.---File: hledger.info,  Node: Customising single-period balance reports,  Prev: Budget report,  Up: balance--11.5.16 Customising single-period balance reports----------------------------------------------------For single-period balance reports displayed in the terminal (only), you-can use '--format FMT' to customise the format and content of each line.-Eg:--$ hledger -f examples/sample.journal balance --format "%20(account) %12(total)"-              assets          $-1-         bank:saving           $1-                cash          $-2-            expenses           $2-                food           $1-            supplies           $1-              income          $-2-               gifts          $-1-              salary          $-1-   liabilities:debts           $1-----------------------------------                                0--   The FMT format string (plus a newline) specifies the formatting-applied to each account/balance pair.  It may contain any suitable text,-with data fields interpolated like so:--   '%[MIN][.MAX](FIELDNAME)'--   * MIN pads with spaces to at least this width (optional)--   * MAX truncates at this width (optional)--   * FIELDNAME must be enclosed in parentheses, and can be one of:--        * 'depth_spacer' - a number of spaces equal to the account's-          depth, or if MIN is specified, MIN * depth spaces.-        * 'account' - the account's name-        * 'total' - the account's balance/posted total, right justified--   Also, FMT can begin with an optional prefix to control how-multi-commodity amounts are rendered:--   * '%_' - render on multiple lines, bottom-aligned (the default)-   * '%^' - render on multiple lines, top-aligned-   * '%,' - render on one line, comma-separated--   There are some quirks.  Eg in one-line mode, '%(depth_spacer)' has no-effect, instead '%(account)' has indentation built in.  Experimentation-may be needed to get pleasing results.--   Some example formats:--   * '%(total)' - the account's total-   * '%-20.20(account)' - the account's name, left justified, padded to-     20 characters and clipped at 20 characters-   * '%,%-50(account) %25(total)' - account name padded to 50-     characters, total padded to 20 characters, with multiple-     commodities rendered on one line-   * '%20(total) %2(depth_spacer)%-(account)' - the default format for-     the single-column balance report---File: hledger.info,  Node: balancesheet,  Next: balancesheetequity,  Prev: balance,  Up: COMMANDS--11.6 balancesheet-=================--balancesheet, bs-This command displays a balance sheet, showing historical ending-balances of asset and liability accounts.  (To see equity as well, use-the balancesheetequity command.)  Amounts are shown with normal positive-sign, as in conventional financial statements.--   The asset and liability accounts shown are those accounts declared-with the 'Asset' or 'Cash' or 'Liability' type, or otherwise all-accounts under a top-level 'asset' or 'liability' account (case-insensitive, plurals allowed).--   Example:--$ hledger balancesheet-Balance Sheet--Assets:-                 $-1  assets-                  $1    bank:saving-                 $-2    cash----------------------                 $-1--Liabilities:-                  $1  liabilities:debts----------------------                  $1--Total:----------------------                   0--   This command is a higher-level variant of the 'balance' command, and-supports many of that command's features, such as multi-period reports.-It is similar to 'hledger balance -H assets liabilities', but with-smarter account detection, and liabilities displayed with their sign-flipped.--   This command also supports the output destination and output format-options The output formats supported are 'txt', 'csv', 'html', and-(experimental) 'json'.---File: hledger.info,  Node: balancesheetequity,  Next: cashflow,  Prev: balancesheet,  Up: COMMANDS--11.7 balancesheetequity-=======================--balancesheetequity, bse-This command displays a balance sheet, showing historical ending-balances of asset, liability and equity accounts.  Amounts are shown-with normal positive sign, as in conventional financial statements.--   The asset, liability and equity accounts shown are those accounts-declared with the 'Asset', 'Cash', 'Liability' or 'Equity' type, or-otherwise all accounts under a top-level 'asset', 'liability' or-'equity' account (case insensitive, plurals allowed).--   Example:--$ hledger balancesheetequity-Balance Sheet With Equity--Assets:-                 $-2  assets-                  $1    bank:saving-                 $-3    cash----------------------                 $-2--Liabilities:-                  $1  liabilities:debts----------------------                  $1--Equity:-          $1  equity:owner----------------------          $1--Total:----------------------                   0--   This command is a higher-level variant of the 'balance' command, and-supports many of that command's features, such as multi-period reports.-It is similar to 'hledger balance -H assets liabilities equity', but-with smarter account detection, and liabilities/equity displayed with-their sign flipped.--   This command also supports the output destination and output format-options The output formats supported are 'txt', 'csv', 'html', and-(experimental) 'json'.---File: hledger.info,  Node: cashflow,  Next: check,  Prev: balancesheetequity,  Up: COMMANDS--11.8 cashflow-=============--cashflow, cf-This command displays a cashflow statement, showing the inflows and-outflows affecting "cash" (ie, liquid) assets.  Amounts are shown with-normal positive sign, as in conventional financial statements.--   The "cash" accounts shown are those accounts declared with the 'Cash'-type, or otherwise all accounts under a top-level 'asset' account (case-insensitive, plural allowed) which do not have 'fixed', 'investment',-'receivable' or 'A/R' in their name.--   Example:--$ hledger cashflow-Cashflow Statement--Cash flows:-                 $-1  assets-                  $1    bank:saving-                 $-2    cash----------------------                 $-1--Total:----------------------                 $-1--   This command is a higher-level variant of the 'balance' command, and-supports many of that command's features, such as multi-period reports.-It is similar to 'hledger balance assets not:fixed not:investment-not:receivable', but with smarter account detection.--   This command also supports the output destination and output format-options The output formats supported are 'txt', 'csv', 'html', and-(experimental) 'json'.---File: hledger.info,  Node: check,  Next: close,  Prev: cashflow,  Up: COMMANDS--11.9 check-==========--check-Check for various kinds of errors in your data.--   hledger provides a number of built-in error checks to help prevent-problems in your data.  Some of these are run automatically; or, you can-use this 'check' command to run them on demand, with no output and a-zero exit code if all is well.  Specify their names (or a prefix) as-argument(s).--   Some examples:--hledger check      # basic checks-hledger check -s   # basic + strict checks-hledger check ordereddates payees  # basic + two other checks--   Here are the checks currently available:--* Menu:--* Basic checks::-* Strict checks::-* Other checks::-* Custom checks::---File: hledger.info,  Node: Basic checks,  Next: Strict checks,  Up: check--11.9.1 Basic checks----------------------These checks are always run automatically, by (almost) all hledger-commands, including 'check':--   * *parseable* - data files are well-formed and can be successfully-     parsed--   * *balancedwithautoconversion* - all transactions are balanced,-     inferring missing amounts where necessary, and possibly converting-     commodities using transaction prices or automatically-inferred-     transaction prices--   * *assertions* - all balance assertions in the journal are passing.-     (This check can be disabled with '-I'/'--ignore-assertions'.)---File: hledger.info,  Node: Strict checks,  Next: Other checks,  Prev: Basic checks,  Up: check--11.9.2 Strict checks-----------------------These additional checks are run when the '-s'/'--strict' (strict mode)-flag is used.  Or, they can be run by giving their names as arguments to-'check':--   * *accounts* - all account names used by transactions have been-     declared--   * *commodities* - all commodity symbols used have been declared--   * *balancednoautoconversion* - transactions are balanced, possibly-     using explicit transaction prices but not inferred ones---File: hledger.info,  Node: Other checks,  Next: Custom checks,  Prev: Strict checks,  Up: check--11.9.3 Other checks----------------------These checks can be run only by giving their names as arguments to-'check'.  They are more specialised and not desirable for everyone,-therefore optional:--   * *ordereddates* - transactions are ordered by date within each file--   * *payees* - all payees used by transactions have been declared--   * *uniqueleafnames* - all account leaf names are unique---File: hledger.info,  Node: Custom checks,  Prev: Other checks,  Up: check--11.9.4 Custom checks-----------------------A few more checks are are available as separate add-on commands, in-https://github.com/simonmichael/hledger/tree/master/bin:--   * *hledger-check-tagfiles* - all tag values containing / (a forward-     slash) exist as file paths--   * *hledger-check-fancyassertions* - more complex balance assertions-     are passing--   You could make similar scripts to perform your own custom checks.-See: Cookbook -> Scripting.---File: hledger.info,  Node: close,  Next: codes,  Prev: check,  Up: COMMANDS--11.10 close-===========--close, equity-Prints a sample "closing" transaction bringing specified account-balances to zero, and an inverse "opening" transaction restoring the-same account balances.--   If like most people you split your journal files by time, eg by year:-at the end of the year you can use this command to "close out" your-asset and liability (and perhaps equity) balances in the old file, and-reinitialise them in the new file.  This helps ensure that report-balances remain correct whether you are including old files or not.-(Because all closing/opening transactions except the very first will-cancel out - see example below.)--   Some people also use this command to close out revenue and expense-balances at the end of an accounting period.  This properly records the-period's profit/loss as "retained earnings" (part of equity), and allows-the accounting equation (A-L=E) to balance, which you could then check-by the bse report's zero total.--   You can print just the closing transaction by using the '--close'-flag, or just the opening transaction with the '--open' flag.--   Their descriptions are 'closing balances' and 'opening balances' by-default; you can customise these with the '--close-desc' and-'--open-desc' options.--   Just one balancing equity posting is used by default, with the amount-left implicit.  The default account name is 'equity:opening/closing-balances'.  You can customise the account name(s) with '--close-acct'-and '--open-acct'.  (If you specify only one of these, it will be used-for both.)--   With '--x/--explicit', the equity posting's amount will be shown-explicitly, and if it involves multiple commodities, there will be a-separate equity posting for each commodity (as in the print command).--   With '--interleaved', each equity posting is shown next to the-posting it balances (good for troubleshooting).--* Menu:--* close and prices::-* close date::-* Example close asset/liability accounts for file transition::-* Hiding opening/closing transactions::-* close and balance assertions::-* Example close revenue/expense accounts to retained earnings::---File: hledger.info,  Node: close and prices,  Next: close date,  Up: close--11.10.1 close and prices---------------------------Transaction prices are ignored (and discarded) by closing/opening-transactions, by default.  With '--show-costs', they are preserved;-there will be a separate equity posting for each cost in each commodity.-This means 'balance -B' reports will look the same after the transition.-Note if you have many foreign currency or investment transactions, this-will generate very large journal entries.---File: hledger.info,  Node: close date,  Next: Example close asset/liability accounts for file transition,  Prev: close and prices,  Up: close--11.10.2 close date---------------------The default closing date is yesterday, or the journal's end date,-whichever is later.--   Unless you are running 'close' on exactly the first day of the new-period, you'll want to override the closing date.  This is done by-specifying a report end date, where "last day of the report period" will-be the closing date.  The opening date is always the following day.  So-to close on (end of) 2020-12-31 and open on (start of) 2021-01-01, any-of these will work:--end date          explanation-argument---------------------------------------------------------------------'-e 2021-01-01'   end dates are exclusive-'-e 2021'         equivalent, per smart dates-'-p 2020'         equivalent, the period's begin date is ignored-'date:2020'       equivalent query---File: hledger.info,  Node: Example close asset/liability accounts for file transition,  Next: Hiding opening/closing transactions,  Prev: close date,  Up: close--11.10.3 Example: close asset/liability accounts for file transition----------------------------------------------------------------------Carrying asset/liability balances from 2020.journal into a new file for-2021:--$ hledger close -f 2020.journal -p 2020 assets liabilities-# copy/paste the closing transaction to the end of 2020.journal-# copy/paste the opening transaction to the start of 2021.journal--   Or:--$ hledger close -f 2020.journal -p 2020 assets liabilities --open  >> 2021.journal  # add 2021's first transaction-$ hledger close -f 2020.journal -p 2020 assets liabilities --close >> 2020.journal  # add 2020's last transaction--   Now,--$ hledger bs -f 2021.journal                   # just new file - balances correct-$ hledger bs -f 2020.journal -f 2021.journal   # old and new files - balances correct-$ hledger bs -f 2020.journal                   # just old files - balances are zero ?-                                               # (exclude final closing txn, see below)---File: hledger.info,  Node: Hiding opening/closing transactions,  Next: close and balance assertions,  Prev: Example close asset/liability accounts for file transition,  Up: close--11.10.4 Hiding opening/closing transactions----------------------------------------------Although the closing/opening transactions cancel out, they will be-visible in reports like 'print' and 'register', creating some visual-clutter.  You can exclude them all with a query, like:--$ hledger print not:desc:'opening|closing'             # less typing-$ hledger print not:'equity:opening/closing balances'  # more precise--   But when reporting on multiple files, this can get a bit tricky; you-may need to keep the earliest opening balances, for a historical-register report; or you may need to suppress a closing transaction, to-see year-end balances.  If you find yourself needing more precise-queries, here's one solution: add more easily-matched tags to-opening/closing transactions, like this:--; 2019.journal-2019-01-01 opening balances  ; earliest opening txn, no tag here-...-2019-12-31 closing balances  ; clopen:2020-...--; 2020.journal-2020-01-01 opening balances  ; clopen:2020-...-2020-12-31 closing balances  ; clopen:2021-...--; 2021.journal-2021-01-01 opening balances  ; clopen:2021-...--   Now with--; all.journal-include 2019.journal-include 2020.journal-include 2021.journal--   you could do eg:--$ hledger -f all.journal reg -H checking not:tag:clopen-    # all years checking register, hiding non-essential opening/closing txns--$ hledger -f all.journal bs -p 2020 not:tag:clopen=2020-    # 2020 year end balances, suppressing 2020 closing txn---File: hledger.info,  Node: close and balance assertions,  Next: Example close revenue/expense accounts to retained earnings,  Prev: Hiding opening/closing transactions,  Up: close--11.10.5 close and balance assertions---------------------------------------The closing and opening transactions will include balance assertions,-verifying that the accounts have first been reset to zero and then-restored to their previous balance.  These provide valuable error-checking, alerting you when things get out of line, but you can ignore-them temporarily with '-I' or just remove them if you prefer.--   You probably shouldn't use status or realness filters (like -C or -R-or 'status:') with 'close', or the generated balance assertions will-depend on these flags.  Likewise, if you run this command with '--auto',-the balance assertions would probably always require '--auto'.--   Multi-day transactions (where some postings have a different date)-break the balance assertions, because the money is temporarily-"invisible" while in transit:--2020/12/30 a purchase made in december, cleared in the next year-    expenses:food          5-    assets:bank:checking  -5  ; date: 2021/1/2--   To fix the assertions, you can add a temporary account to track such-in-transit money (splitting the multi-day transaction into two-single-day transactions):--; in 2020.journal:-2020/12/30 a purchase made in december, cleared in the next year-    expenses:food          5-    liabilities:pending--; in 2021.journal:-2021/1/2 clearance of last year's pending transactions-    liabilities:pending    5 = 0-    assets:bank:checking---File: hledger.info,  Node: Example close revenue/expense accounts to retained earnings,  Prev: close and balance assertions,  Up: close--11.10.6 Example: close revenue/expense accounts to retained earnings-----------------------------------------------------------------------For this, use '--close' to suppress the opening transaction, as it's not-needed.  Also you'll want to change the equity account name to your-equivalent of "equity:retained earnings".--   Closing 2021's first quarter revenues/expenses:--$ hledger close -f 2021.journal --close revenues expenses -p 2021Q1 \-    --close-acct='equity:retained earnings' >> 2021.journal--   The same, using the default journal and current year:--$ hledger close --close revenues expenses -p Q1 \-    --close-acct='equity:retained earnings' >> $LEDGER_FILE--   Now, the first quarter's balance sheet should show a zero (unless you-are using @/@@ notation without equity postings):--$ hledger bse -p Q1--   And we must suppress the closing transaction to see the first-quarter's income statement (using the description; 'not:'retained-earnings'' won't work here):--$ hledger is -p Q1 not:desc:'closing balances'---File: hledger.info,  Node: codes,  Next: commodities,  Prev: close,  Up: COMMANDS--11.11 codes-===========--codes-List the codes seen in transactions, in the order parsed.--   This command prints the value of each transaction's code field, in-the order transactions were parsed.  The transaction code is an optional-value written in parentheses between the date and description, often-used to store a cheque number, order number or similar.--   Transactions aren't required to have a code, and missing or empty-codes will not be shown by default.  With the '-E'/'--empty' flag, they-will be printed as blank lines.--   You can add a query to select a subset of transactions.--   Examples:--1/1 (123)- (a)  1--1/1 ()- (a)  1--1/1- (a)  1--1/1 (126)- (a)  1--$ hledger codes-123-124-126--$ hledger codes -E-123-124---126---File: hledger.info,  Node: commodities,  Next: descriptions,  Prev: codes,  Up: COMMANDS--11.12 commodities-=================--commodities-List all commodity/currency symbols used or declared in the journal.---File: hledger.info,  Node: descriptions,  Next: diff,  Prev: commodities,  Up: COMMANDS--11.13 descriptions-==================--descriptions-List the unique descriptions that appear in transactions.--   This command lists the unique descriptions that appear in-transactions, in alphabetic order.  You can add a query to select a-subset of transactions.--   Example:--$ hledger descriptions-Store Name-Gas Station | Petrol-Person A---File: hledger.info,  Node: diff,  Next: files,  Prev: descriptions,  Up: COMMANDS--11.14 diff-==========--diff-Compares a particular account's transactions in two input files.  It-shows any transactions to this account which are in one file but not in-the other.--   More precisely, for each posting affecting this account in either-file, it looks for a corresponding posting in the other file which posts-the same amount to the same account (ignoring date, description, etc.)-Since postings not transactions are compared, this also works when-multiple bank transactions have been combined into a single journal-entry.--   This is useful eg if you have downloaded an account's transactions-from your bank (eg as CSV data).  When hledger and your bank disagree-about the account balance, you can compare the bank data with your-journal to find out the cause.--   Examples:--$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro -These transactions are in the first file only:--2014/01/01 Opening Balances-    assets:bank:giro              EUR ...-    ...-    equity:opening balances       EUR -...--These transactions are in the second file only:---File: hledger.info,  Node: files,  Next: help,  Prev: diff,  Up: COMMANDS--11.15 files-===========--files-List all files included in the journal.  With a REGEX argument, only-file names matching the regular expression (case sensitive) are shown.---File: hledger.info,  Node: help,  Next: import,  Prev: files,  Up: COMMANDS--11.16 help-==========--help-Show the hledger user manual in one of several formats, optionally-positioned at a given TOPIC (if possible).--   TOPIC is any heading in the manual, or the start of any heading (but-not the middle).  It is case insensitive.--   Some examples: 'commands', 'print', 'forecast', '"auto postings"',-'"commodity column"'.--   This command shows the user manual built in to this hledger version.-It can be useful if the correct version of the hledger manual, or the-usual viewing tools, are not installed on your system.--   By default it uses the best viewer it can find in $PATH, in this-order: 'info', 'man', $PAGER (unless a topic is specified), 'less', or-stdout.  When run non-interactively, it always uses stdout.  Or you can-select a particular viewer with the '-i' (info), '-m' (man), or '-p'-(pager) flags.---File: hledger.info,  Node: import,  Next: incomestatement,  Prev: help,  Up: COMMANDS--11.17 import-============--import-Read new transactions added to each FILE since last run, and add them to-the main journal file.  Or with -dry-run, just print the transactions-that would be added.  Or with -catchup, just mark all of the FILEs'-transactions as imported, without actually importing any.--   Unlike other hledger commands, with 'import' the journal file is an-output file, and will be modified, though only by appending (existing-data will not be changed).  The input files are specified as arguments,-so to import one or more CSV files to your main journal, you will run-'hledger import bank.csv' or perhaps 'hledger import *.csv'.--   Note you can import from any file format, though CSV files are the-most common import source, and these docs focus on that case.--* Menu:--* Deduplication::-* Import testing::-* Importing balance assignments::-* Commodity display styles::---File: hledger.info,  Node: Deduplication,  Next: Import testing,  Up: import--11.17.1 Deduplication------------------------As a convenience 'import' does _deduplication_ while reading-transactions.  This does not mean "ignore transactions that look the-same", but rather "ignore transactions that have been seen before".-This is intended for when you are periodically importing foreign data-which may contain already-imported transactions.  So eg, if every day-you download bank CSV files containing redundant data, you can safely-run 'hledger import bank.csv' and only new transactions will be-imported.  ('import' is idempotent.)--   Since the items being read (CSV records, eg) often do not come with-unique identifiers, hledger detects new transactions by date, assuming-that:--  1. new items always have the newest dates-  2. item dates do not change across reads-  3. and items with the same date remain in the same relative order-     across reads.--   These are often true of CSV files representing transactions, or true-enough so that it works pretty well in practice.  1 is important, but-violations of 2 and 3 amongst the old transactions won't matter (and if-you import often, the new transactions will be few, so less likely to be-the ones affected).--   hledger remembers the latest date processed in each input file by-saving a hidden ".latest" state file in the same directory.  Eg when-reading 'finance/bank.csv', it will look for and update the-'finance/.latest.bank.csv' state file.  The format is simple: one or-more lines containing the same ISO-format date (YYYY-MM-DD), meaning "I-have processed transactions up to this date, and this many of them on-that date."  Normally you won't see or manipulate these state files-yourself.  But if needed, you can delete them to reset the state (making-all transactions "new"), or you can construct them to "catch up" to a-certain date.--   Note deduplication (and updating of state files) can also be done by-'print --new', but this is less often used.---File: hledger.info,  Node: Import testing,  Next: Importing balance assignments,  Prev: Deduplication,  Up: import--11.17.2 Import testing-------------------------With '--dry-run', the transactions that will be imported are printed to-the terminal, without updating your journal or state files.  The output-is valid journal format, like the print command, so you can re-parse it.-Eg, to see any importable transactions which CSV rules have not-categorised:--$ hledger import --dry bank.csv | hledger -f- -I print unknown--   or (live updating):--$ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown'---File: hledger.info,  Node: Importing balance assignments,  Next: Commodity display styles,  Prev: Import testing,  Up: import--11.17.3 Importing balance assignments----------------------------------------Entries added by import will have their posting amounts made explicit-(like 'hledger print -x').  This means that any balance assignments in-imported files must be evaluated; but, imported files don't get to see-the main file's account balances.  As a result, importing entries with-balance assignments (eg from an institution that provides only balances-and not posting amounts) will probably generate incorrect posting-amounts.  To avoid this problem, use print instead of import:--$ hledger print IMPORTFILE [--new] >> $LEDGER_FILE--   (If you think import should leave amounts implicit like print does,-please test it and send a pull request.)---File: hledger.info,  Node: Commodity display styles,  Prev: Importing balance assignments,  Up: import--11.17.4 Commodity display styles-----------------------------------Imported amounts will be formatted according to the canonical commodity-styles (declared or inferred) in the main journal file.---File: hledger.info,  Node: incomestatement,  Next: notes,  Prev: import,  Up: COMMANDS--11.18 incomestatement-=====================--incomestatement, is--   This command displays an income statement, showing revenues and-expenses during one or more periods.  Amounts are shown with normal-positive sign, as in conventional financial statements.--   The revenue and expense accounts shown are those accounts declared-with the 'Revenue' or 'Expense' type, or otherwise all accounts under a-top-level 'revenue' or 'income' or 'expense' account (case insensitive,-plurals allowed).--   Example:--$ hledger incomestatement-Income Statement--Revenues:-                 $-2  income-                 $-1    gifts-                 $-1    salary----------------------                 $-2--Expenses:-                  $2  expenses-                  $1    food-                  $1    supplies----------------------                  $2--Total:----------------------                   0--   This command is a higher-level variant of the 'balance' command, and-supports many of that command's features, such as multi-period reports.-It is similar to 'hledger balance '(revenues|income)' expenses', but-with smarter account detection, and revenues/income displayed with their-sign flipped.--   This command also supports the output destination and output format-options The output formats supported are 'txt', 'csv', 'html', and-(experimental) 'json'.---File: hledger.info,  Node: notes,  Next: payees,  Prev: incomestatement,  Up: COMMANDS--11.19 notes-===========--notes-List the unique notes that appear in transactions.--   This command lists the unique notes that appear in transactions, in-alphabetic order.  You can add a query to select a subset of-transactions.  The note is the part of the transaction description after-a | character (or if there is no |, the whole description).--   Example:--$ hledger notes-Petrol-Snacks---File: hledger.info,  Node: payees,  Next: prices,  Prev: notes,  Up: COMMANDS--11.20 payees-============--payees-List the unique payee/payer names that appear in transactions.--   This command lists unique payee/payer names which have been declared-with payee directives (-declared), used in transaction descriptions-(-used), or both (the default).--   The payee/payer is the part of the transaction description before a |-character (or if there is no |, the whole description).--   You can add query arguments to select a subset of transactions.  This-implies -used.--   Example:--$ hledger payees-Store Name-Gas Station-Person A---File: hledger.info,  Node: prices,  Next: print,  Prev: payees,  Up: COMMANDS--11.21 prices-============--prices-Print market price directives from the journal.  With--infer-market-prices, generate additional market prices from transaction-prices.  With -infer-reverse-prices, also generate market prices by-inverting transaction prices.  Prices (and postings providing-transaction prices) can be filtered by a query.  Price amounts are-displayed with their full precision.---File: hledger.info,  Node: print,  Next: print-unique,  Prev: prices,  Up: COMMANDS--11.22 print-===========--print-Show transaction journal entries, sorted by date.--   The print command displays full journal entries (transactions) from-the journal file, sorted by date (or with '--date2', by secondary date).--   Amounts are shown mostly normalised to commodity display style, eg-the placement of commodity symbols will be consistent.  All of their-decimal places are shown, as in the original journal entry (with one-alteration: in some cases trailing zeroes are added.)--   Amounts are shown right-aligned within each transaction (but not-across all transactions).--   Directives and inter-transaction comments are not shown, currently.-This means the print command is somewhat lossy, and if you are using it-to reformat your journal you should take care to also copy over the-directives and file-level comments.--   Eg:--$ hledger print-2008/01/01 income-    assets:bank:checking            $1-    income:salary                  $-1--2008/06/01 gift-    assets:bank:checking            $1-    income:gifts                   $-1--2008/06/02 save-    assets:bank:saving              $1-    assets:bank:checking           $-1--2008/06/03 * eat & shop-    expenses:food                $1-    expenses:supplies            $1-    assets:cash                 $-2--2008/12/31 * pay off-    liabilities:debts               $1-    assets:bank:checking           $-1--   print's output is usually a valid hledger journal, and you can-process it again with a second hledger command.  This can be useful for-certain kinds of search, eg:--# Show running total of food expenses paid from cash.-# -f- reads from stdin. -I/--ignore-assertions is sometimes needed.-$ hledger print assets:cash | hledger -f- -I reg expenses:food--   There are some situations where print's output can become-unparseable:--   * Valuation affects posting amounts but not balance assertion or-     balance assignment amounts, potentially causing those to fail.-   * Auto postings can generate postings with too many missing amounts.--   Normally, the journal entry's explicit or implicit amount style is-preserved.  For example, when an amount is omitted in the journal, it-will not appear in the output.  Similarly, when a transaction price is-implied but not written, it will not appear in the output.  You can use-the '-x'/'--explicit' flag to make all amounts and transaction prices-explicit, which can be useful for troubleshooting or for making your-journal more readable and robust against data entry errors.  '-x' is-also implied by using any of '-B','-V','-X','--value'.--   Note, '-x'/'--explicit' will cause postings with a multi-commodity-amount (these can arise when a multi-commodity transaction has an-implicit amount) to be split into multiple single-commodity postings,-keeping the output parseable.--   With '-B'/'--cost', amounts with transaction prices are converted to-cost using that price.  This can be used for troubleshooting.--   With '-m'/'--match' and a STR argument, print will show at most one-transaction: the one one whose description is most similar to STR, and-is most recent.  STR should contain at least two characters.  If there-is no similar-enough match, no transaction will be shown.--   With '--new', hledger prints only transactions it has not seen on a-previous run.  This uses the same deduplication system as the 'import'-command.  (See import's docs for details.)--   This command also supports the output destination and output format-options The output formats supported are 'txt', 'csv', and-(experimental) 'json' and 'sql'.--   Here's an example of print's CSV output:--$ hledger print -Ocsv-"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment"-"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","",""-"1","2008/01/01","","","","income","","income:salary","-1","$","1","","",""-"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","",""-"2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","",""-"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","",""-"3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","",""-"4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","",""-"4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","",""-"4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","",""-"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""-"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""--   * There is one CSV record per posting, with the parent transaction's-     fields repeated.-   * The "txnidx" (transaction index) field shows which postings belong-     to the same transaction.  (This number might change if transactions-     are reordered within the file, files are parsed/included in a-     different order, etc.)-   * The amount is separated into "commodity" (the symbol) and "amount"-     (numeric quantity) fields.-   * The numeric amount is repeated in either the "credit" or "debit"-     column, for convenience.  (Those names are not accurate in the-     accounting sense; it just puts negative amounts under credit and-     zero or greater amounts under debit.)---File: hledger.info,  Node: print-unique,  Next: register,  Prev: print,  Up: COMMANDS--11.23 print-unique-==================--print-unique-Print transactions which do not reuse an already-seen description.--   Example:--$ cat unique.journal-1/1 test- (acct:one)  1-2/2 test- (acct:two)  2-$ LEDGER_FILE=unique.journal hledger print-unique-(-f option not supported)-2015/01/01 test-    (acct:one)             1---File: hledger.info,  Node: register,  Next: register-match,  Prev: print-unique,  Up: COMMANDS--11.24 register-==============--register, reg-Show postings and their running total.--   The register command displays matched postings, across all accounts,-in date order, with their running total or running historical balance.-(See also the 'aregister' command, which shows matched transactions in a-specific account.)--   register normally shows line per posting, but note that-multi-commodity amounts will occupy multiple lines (one line per-commodity).--   It is typically used with a query selecting a particular account, to-see that account's activity:--$ hledger register checking-2008/01/01 income               assets:bank:checking            $1           $1-2008/06/01 gift                 assets:bank:checking            $1           $2-2008/06/02 save                 assets:bank:checking           $-1           $1-2008/12/31 pay off              assets:bank:checking           $-1            0--   With -date2, it shows and sorts by secondary date instead.--   The '--historical'/'-H' flag adds the balance from any undisplayed-prior postings to the running total.  This is useful when you want to-see only recent activity, with a historically accurate running balance:--$ hledger register checking -b 2008/6 --historical-2008/06/01 gift                 assets:bank:checking            $1           $2-2008/06/02 save                 assets:bank:checking           $-1           $1-2008/12/31 pay off              assets:bank:checking           $-1            0--   The '--depth' option limits the amount of sub-account detail-displayed.--   The '--average'/'-A' flag shows the running average posting amount-instead of the running total (so, the final number displayed is the-average for the whole report period).  This flag implies '--empty' (see-below).  It is affected by '--historical'.  It works best when showing-just one account and one commodity.--   The '--related'/'-r' flag shows the _other_ postings in the-transactions of the postings which would normally be shown.--   The '--invert' flag negates all amounts.  For example, it can be used-on an income account where amounts are normally displayed as negative-numbers.  It's also useful to show postings on the checking account-together with the related account:--$ hledger register --related --invert assets:checking--   With a reporting interval, register shows summary postings, one per-interval, aggregating the postings to each account:--$ hledger register --monthly income-2008/01                 income:salary                          $-1          $-1-2008/06                 income:gifts                           $-1          $-2--   Periods with no activity, and summary postings with a zero amount,-are not shown by default; use the '--empty'/'-E' flag to see them:--$ hledger register --monthly income -E-2008/01                 income:salary                          $-1          $-1-2008/02                                                          0          $-1-2008/03                                                          0          $-1-2008/04                                                          0          $-1-2008/05                                                          0          $-1-2008/06                 income:gifts                           $-1          $-2-2008/07                                                          0          $-2-2008/08                                                          0          $-2-2008/09                                                          0          $-2-2008/10                                                          0          $-2-2008/11                                                          0          $-2-2008/12                                                          0          $-2--   Often, you'll want to see just one line per interval.  The '--depth'-option helps with this, causing subaccounts to be aggregated:--$ hledger register --monthly assets --depth 1h-2008/01                 assets                                  $1           $1-2008/06                 assets                                 $-1            0-2008/12                 assets                                 $-1          $-1--   Note when using report intervals, if you specify start/end dates-these will be adjusted outward if necessary to contain a whole number of-intervals.  This ensures that the first and last intervals are full-length and comparable to the others in the report.--* Menu:--* Custom register output::---File: hledger.info,  Node: Custom register output,  Up: register--11.24.1 Custom register output---------------------------------register uses the full terminal width by default, except on windows.-You can override this by setting the 'COLUMNS' environment variable (not-a bash shell variable) or by using the '--width'/'-w' option.--   The description and account columns normally share the space equally-(about half of (width - 40) each).  You can adjust this by adding a-description width as part of -width's argument, comma-separated:-'--width W,D' .  Here's a diagram (won't display correctly in -help):--<--------------------------------- width (W) ---------------------------------->-date (10)  description (D)       account (W-41-D)     amount (12)   balance (12)-DDDDDDDDDD dddddddddddddddddddd  aaaaaaaaaaaaaaaaaaa  AAAAAAAAAAAA  AAAAAAAAAAAA--   and some examples:--$ hledger reg                     # use terminal width (or 80 on windows)-$ hledger reg -w 100              # use width 100-$ COLUMNS=100 hledger reg         # set with one-time environment variable-$ export COLUMNS=100; hledger reg # set till session end (or window resize)-$ hledger reg -w 100,40           # set overall width 100, description width 40-$ hledger reg -w $COLUMNS,40      # use terminal width, & description width 40--   This command also supports the output destination and output format-options The output formats supported are 'txt', 'csv', and-(experimental) 'json'.---File: hledger.info,  Node: register-match,  Next: rewrite,  Prev: register,  Up: COMMANDS--11.25 register-match-====================--register-match-Print the one posting whose transaction description is closest to DESC,-in the style of the register command.  If there are multiple equally-good matches, it shows the most recent.  Query options (options, not-arguments) can be used to restrict the search space.  Helps-ledger-autosync detect already-seen transactions when importing.---File: hledger.info,  Node: rewrite,  Next: roi,  Prev: register-match,  Up: COMMANDS--11.26 rewrite-=============--rewrite-Print all transactions, rewriting the postings of matched transactions.-For now the only rewrite available is adding new postings, like print--auto.--   This is a start at a generic rewriter of transaction entries.  It-reads the default journal and prints the transactions, like print, but-adds one or more specified postings to any transactions matching QUERY.-The posting amounts can be fixed, or a multiplier of the existing-transaction's first posting amount.--   Examples:--$ hledger-rewrite.hs ^income --add-posting '(liabilities:tax)  *.33  ; income tax' --add-posting '(reserve:gifts)  $100'-$ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts)  *-1"'-$ hledger-rewrite.hs -f rewrites.hledger--   rewrites.hledger may consist of entries like:--= ^income amt:<0 date:2017-  (liabilities:tax)  *0.33  ; tax on income-  (reserve:grocery)  *0.25  ; reserve 25% for grocery-  (reserve:)  *0.25  ; reserve 25% for grocery--   Note the single quotes to protect the dollar sign from bash, and the-two spaces between account and amount.--   More:--$ hledger rewrite -- [QUERY]        --add-posting "ACCT  AMTEXPR" ...-$ hledger rewrite -- ^income        --add-posting '(liabilities:tax)  *.33'-$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts)  *-1"'-$ hledger rewrite -- ^income        --add-posting '(budget:foreign currency)  *0.25 JPY; diversify'--   Argument for '--add-posting' option is a usual posting of transaction-with an exception for amount specification.  More precisely, you can use-''*'' (star symbol) before the amount to indicate that that this is a-factor for an amount of original matched posting.  If the amount-includes a commodity name, the new posting amount will be in the new-commodity; otherwise, it will be in the matched posting amount's-commodity.--* Menu:--* Re-write rules in a file::-* Diff output format::-* rewrite vs print --auto::---File: hledger.info,  Node: Re-write rules in a file,  Next: Diff output format,  Up: rewrite--11.26.1 Re-write rules in a file-----------------------------------During the run this tool will execute so called "Automated Transactions"-found in any journal it process.  I.e instead of specifying this-operations in command line you can put them in a journal file.--$ rewrite-rules.journal--   Make contents look like this:--= ^income-    (liabilities:tax)  *.33--= expenses:gifts-    budget:gifts  *-1-    assets:budget  *1--   Note that ''='' (equality symbol) that is used instead of date in-transactions you usually write.  It indicates the query by which you-want to match the posting to add new ones.--$ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal--   This is something similar to the commands pipeline:--$ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax)  *.33' \-  | hledger rewrite -- -f - expenses:gifts      --add-posting 'budget:gifts  *-1'       \-                                                --add-posting 'assets:budget  *1'       \-  > rewritten-tidy-output.journal--   It is important to understand that relative order of such entries in-journal is important.  You can re-use result of previously added-postings.---File: hledger.info,  Node: Diff output format,  Next: rewrite vs print --auto,  Prev: Re-write rules in a file,  Up: rewrite--11.26.2 Diff output format-----------------------------To use this tool for batch modification of your journal files you may-find useful output in form of unified diff.--$ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax)  *.33'--   Output might look like:----- /tmp/examples/sample.journal-+++ /tmp/examples/sample.journal-@@ -18,3 +18,4 @@- 2008/01/01 income--    assets:bank:checking  $1-+    assets:bank:checking            $1-     income:salary-+    (liabilities:tax)                0-@@ -22,3 +23,4 @@- 2008/06/01 gift--    assets:bank:checking  $1-+    assets:bank:checking            $1-     income:gifts-+    (liabilities:tax)                0--   If you'll pass this through 'patch' tool you'll get transactions-containing the posting that matches your query be updated.  Note that-multiple files might be update according to list of input files-specified via '--file' options and 'include' directives inside of these-files.--   Be careful.  Whole transaction being re-formatted in a style of-output from 'hledger print'.--   See also:--   https://github.com/simonmichael/hledger/issues/99---File: hledger.info,  Node: rewrite vs print --auto,  Prev: Diff output format,  Up: rewrite--11.26.3 rewrite vs. print -auto----------------------------------This command predates print -auto, and currently does much the same-thing, but with these differences:--   * with multiple files, rewrite lets rules in any file affect all-     other files.  print -auto uses standard directive scoping; rules-     affect only child files.--   * rewrite's query limits which transactions can be rewritten; all are-     printed.  print -auto's query limits which transactions are-     printed.--   * rewrite applies rules specified on command line or in the journal.-     print -auto applies rules specified in the journal.---File: hledger.info,  Node: roi,  Next: stats,  Prev: rewrite,  Up: COMMANDS--11.27 roi-=========--roi-Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on-your investments.--   At a minimum, you need to supply a query (which could be just an-account name) to select your investment(s) with '--inv', and another-query to identify your profit and loss transactions with '--pnl'.--   If you do not record changes in the value of your investment-manually, or do not require computation of time-weighted return (TWR),-'--pnl' could be an empty query ('--pnl ""' or '--pnl STR' where 'STR'-does not match any of your accounts).--   This command will compute and display the internalized rate of return-(IRR) and time-weighted rate of return (TWR) for your investments for-the time period requested.  Both rates of return are annualized before-display, regardless of the length of reporting interval.--   Price directives will be taken into account if you supply appropriate-'--cost' or '--value' flags (see VALUATION).--   Note, in some cases this report can fail, for these reasons:--   * Error (NotBracketed): No solution for Internal Rate of Return-     (IRR). Possible causes: IRR is huge (>1000000%), balance of-     investment becomes negative at some point in time.-   * Error (SearchFailed): Failed to find solution for Internal Rate of-     Return (IRR). Either search does not converge to a solution, or-     converges too slowly.--   Examples:--   * Using roi to compute total return of investment in stocks:-     https://github.com/simonmichael/hledger/blob/master/examples/roi-unrealised.ledger--   * Cookbook -> Return on Investment--* Menu:--* Spaces and special characters in --inv and --pnl::-* Semantics of --inv and --pnl::-* IRR and TWR explained::---File: hledger.info,  Node: Spaces and special characters in --inv and --pnl,  Next: Semantics of --inv and --pnl,  Up: roi--11.27.1 Spaces and special characters in '--inv' and-------------------------------------------------------'--pnl' Note that '--inv' and '--pnl''s argument is a query, and queries-could have several space-separated terms (see QUERIES).--   To indicate that all search terms form single command-line argument,-you will need to put them in quotes (see Special characters):--$ hledger roi --inv 'term1 term2 term3 ...'--   If any query terms contain spaces themselves, you will need an extra-level of nested quoting, eg:--$ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'"---File: hledger.info,  Node: Semantics of --inv and --pnl,  Next: IRR and TWR explained,  Prev: Spaces and special characters in --inv and --pnl,  Up: roi--11.27.2 Semantics of '--inv' and '--pnl'-------------------------------------------Query supplied to '--inv' has to match all transactions that are related-to your investment.  Transactions not matching '--inv' will be ignored.--   In these transactions, ROI will conside postings that match '--inv'-to be "investment postings" and other postings (not matching '--inv')-will be sorted into two categories: "cash flow" and "profit and loss",-as ROI needs to know which part of the investment value is your-contributions and which is due to the return on investment.--   * "Cash flow" is depositing or withdrawing money, buying or selling-     assets, or otherwise converting between your investment commodity-     and any other commodity.  Example:--     2019-01-01 Investing in Snake Oil-       assets:cash          -$100-       investment:snake oil-     -     2020-01-01 Selling my Snake Oil-       assets:cash           $10-       investment:snake oil  = 0--   * "Profit and loss" is change in the value of your investment:--     2019-06-01 Snake Oil falls in value-       investment:snake oil  = $57-       equity:unrealized profit or loss--   All non-investment postings are assumed to be "cash flow", unless-they match '--pnl' query.  Changes in value of your investment due to-"profit and loss" postings will be considered as part of your investment-return.--   Example: if you use '--inv snake --pnl equity:unrealized', then-postings in the example below would be classifed as:--2019-01-01 Snake Oil #1-  assets:cash          -$100   ; cash flow posting-  investment:snake oil         ; investment posting--2019-03-01 Snake Oil #2-  equity:unrealized pnl  -$100 ; profit and loss posting-  snake oil                    ; investment posting--2019-07-01 Snake Oil #3-  equity:unrealized pnl        ; profit and loss posting-  cash          -$100          ; cash flow posting-  snake oil     $50            ; investment posting---File: hledger.info,  Node: IRR and TWR explained,  Prev: Semantics of --inv and --pnl,  Up: roi--11.27.3 IRR and TWR explained--------------------------------"ROI" stands for "return on investment".  Traditionally this was-computed as a difference between current value of investment and its-initial value, expressed in percentage of the initial value.--   However, this approach is only practical in simple cases, where-investments receives no in-flows or out-flows of money, and where rate-of growth is fixed over time.  For more complex scenarios you need-different ways to compute rate of return, and this command implements-two of them: IRR and TWR.--   Internal rate of return, or "IRR" (also called "money-weighted rate-of return") takes into account effects of in-flows and out-flows.-Naively, if you are withdrawing from your investment, your future gains-would be smaller (in absolute numbers), and will be a smaller percentage-of your initial investment, and if you are adding to your investment,-you will receive bigger absolute gains (but probably at the same rate of-return).  IRR is a way to compute rate of return for each period between-in-flow or out-flow of money, and then combine them in a way that gives-you a compound annual rate of return that investment is expected to-generate.--   As mentioned before, in-flows and out-flows would be any cash that-you personally put in or withdraw, and for the "roi" command, these are-the postings that match the query in the'--inv' argument and NOT match-the query in the'--pnl' argument.--   If you manually record changes in the value of your investment as-transactions that balance them against "profit and loss" (or "unrealized-gains") account or use price directives, then in order for IRR to-compute the precise effect of your in-flows and out-flows on the rate of-return, you will need to record the value of your investement on or-close to the days when in- or out-flows occur.--   In technical terms, IRR uses the same approach as computation of net-present value, and tries to find a discount rate that makes net present-value of all the cash flows of your investment to add up to zero.  This-could be hard to wrap your head around, especially if you haven't done-discounted cash flow analysis before.  Implementation of IRR in hledger-should produce results that match the 'XIRR' formula in Excel.--   Second way to compute rate of return that 'roi' command implements is-called "time-weighted rate of return" or "TWR". Like IRR, it will also-break the history of your investment into periods between in-flows,-out-flows and value changes, to compute rate of return per each period-and then a compound rate of return.  However, internal workings of TWR-are quite different.--   TWR represents your investment as an imaginary "unit fund" where-in-flows/ out-flows lead to buying or selling "units" of your investment-and changes in its value change the value of "investment unit".  Change-in "unit price" over the reporting period gives you rate of return of-your investment.--   References: * Explanation of rate of return * Explanation of IRR *-Explanation of TWR * Examples of computing IRR and TWR and discussion of-the limitations of both metrics---File: hledger.info,  Node: stats,  Next: tags,  Prev: roi,  Up: COMMANDS--11.28 stats-===========--stats-Show journal and performance statistics.--   The stats command displays summary information for the whole journal,-or a matched part of it.  With a reporting interval, it shows a report-for each report period.--   At the end, it shows (in the terminal) the overall run time and-number of transactions processed per second.  Note these are approximate-and will vary based on machine, current load, data size, hledger-version, haskell lib versions, GHC version..  but they may be of-interest.  The 'stats' command's run time is similar to that of a-single-column balance report.--   Example:--$ hledger stats -f examples/1000x1000x10.journal-Main file                : /Users/simon/src/hledger/examples/1000x1000x10.journal-Included files           : -Transactions span        : 2000-01-01 to 2002-09-27 (1000 days)-Last transaction         : 2002-09-26 (6995 days ago)-Transactions             : 1000 (1.0 per day)-Transactions last 30 days: 0 (0.0 per day)-Transactions last 7 days : 0 (0.0 per day)-Payees/descriptions      : 1000-Accounts                 : 1000 (depth 10)-Commodities              : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z)-Market prices            : 1000 (A)--Run time                 : 0.12 s-Throughput               : 8342 txns/s--   This command also supports output destination and output format-selection.---File: hledger.info,  Node: tags,  Next: test,  Prev: stats,  Up: COMMANDS--11.29 tags-==========--tags-List the unique tag names used in the journal.  With a TAGREGEX-argument, only tag names matching the regular expression (case-insensitive) are shown.  With QUERY arguments, only transactions-matching the query are considered.--   With the -values flag, the tags' unique values are listed instead.--   With -parsed flag, all tags or values are shown in the order they are-parsed from the input data, including duplicates.--   With -E/-empty, any blank/empty values will also be shown, otherwise-they are omitted.---File: hledger.info,  Node: test,  Next: About add-on commands,  Prev: tags,  Up: COMMANDS--11.30 test-==========--test-Run built-in unit tests.--   This command runs the unit tests built in to hledger and hledger-lib,-printing the results on stdout.  If any test fails, the exit code will-be non-zero.--   This is mainly used by hledger developers, but you can also use it to-sanity-check the installed hledger executable on your platform.  All-tests are expected to pass - if you ever see a failure, please report as-a bug!--   This command also accepts tasty test runner options, written after a-- (double hyphen).  Eg to run only the tests in Hledger.Data.Amount,-with ANSI colour codes disabled:--$ hledger test -- -pData.Amount --color=never--   For help on these, see https://github.com/feuerbach/tasty#options-('-- --help' currently doesn't show them).---File: hledger.info,  Node: About add-on commands,  Prev: test,  Up: COMMANDS--11.31 About add-on commands-===========================--Add-on commands are programs or scripts in your PATH--   * whose name starts with 'hledger-'-   * whose name ends with a recognised file extension:-     '.bat','.com','.exe', '.hs','.lhs','.pl','.py','.rb','.rkt','.sh'-     or none-   * and (on unix, mac) which are executable by the current user.--   Add-ons are a relatively easy way to add local features or experiment-with new ideas.  They can be written in any language, but haskell-scripts have a big advantage: they can use the same hledger library-functions that built-in commands use for command-line options, parsing-and reporting.  Some experimental/example add-on scripts can be found in-the hledger repo's bin/ directory.--   Note in a hledger command line, add-on command flags must have a-double dash ('--') preceding them.  Eg you must write:--$ hledger web -- --serve--   and not:--$ hledger web --serve--   (because the '--serve' flag belongs to 'hledger-web', not 'hledger').--   The '-h/--help' and '--version' flags don't require '--'.--   If you have any trouble with this, remember you can always run the-add-on program directly, eg:--$ hledger-web --serve---File: hledger.info,  Node: JOURNAL FORMAT,  Next: CSV FORMAT,  Prev: COMMANDS,  Up: Top--12 JOURNAL FORMAT-*****************--hledger's default file format, representing a General Journal.--   hledger's usual data source is a plain text file containing journal-entries in hledger journal format.  This file represents a standard-accounting general journal.  I use file names ending in '.journal', but-that's not required.  The journal file contains a number of transaction-entries, each describing a transfer of money (or any commodity) between-two or more named accounts, in a simple format readable by both hledger-and humans.--   hledger's journal format is a compatible subset, mostly, of ledger's-journal format, so hledger can work with compatible ledger journal files-as well.  It's safe, and encouraged, to run both hledger and ledger on-the same journal file, eg to validate the results you're getting.--   You can use hledger without learning any more about this file; just-use the add or web or import commands to create and update it.--   Many users, though, edit the journal file with a text editor, and-track changes with a version control system such as git.  Editor addons-such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and-hledger-vscode for Visual Studio Code, make this easier, adding colour,-formatting, tab completion, and useful commands.  See Editor-configuration at hledger.org for the full list.--   Here's a description of each part of the file format (and hledger's-data model).  These are mostly in the order you'll use them, but in some-cases related concepts have been grouped together for easy reference, or-linked before they are introduced, so feel free to skip over anything-that looks unnecessary right now.--* Menu:--* Transactions::-* Dates::-* Status::-* Code::-* Description::-* Comments::-* Tags::-* Postings::-* Account names::-* Amounts::-* Transaction prices::-* Lot prices lot dates::-* Balance assertions::-* Balance assignments::-* Directives::-* Directives and multiple files::-* Comment blocks::-* Including other files::-* Default year::-* Declaring payees::-* Declaring the decimal mark::-* Declaring commodities::-* Default commodity::-* Declaring market prices::-* Declaring accounts::-* Rewriting accounts::-* Default parent account::-* Periodic transactions::-* Auto postings::---File: hledger.info,  Node: Transactions,  Next: Dates,  Up: JOURNAL FORMAT--12.1 Transactions-=================--Transactions are the main unit of information in a journal file.  They-represent events, typically a movement of some quantity of commodities-between two or more named accounts.--   Each transaction is recorded as a journal entry, beginning with a-simple date in column 0.  This can be followed by any of the following-optional fields, separated by spaces:--   * a status character (empty, '!', or '*')-   * a code (any short number or text, enclosed in parentheses)-   * a description (any remaining text until end of line or a semicolon)-   * a comment (any remaining text following a semicolon until end of-     line, and any following indented lines beginning with a semicolon)-   * 0 or more indented _posting_ lines, describing what was transferred-     and the accounts involved (indented comment lines are also allowed,-     but not blank lines or non-indented lines).--   Here's a simple journal file containing one transaction:--2008/01/01 income-  assets:bank:checking   $1-  income:salary         $-1---File: hledger.info,  Node: Dates,  Next: Status,  Prev: Transactions,  Up: JOURNAL FORMAT--12.2 Dates-==========--* Menu:--* Simple dates::-* Secondary dates::-* Posting dates::---File: hledger.info,  Node: Simple dates,  Next: Secondary dates,  Up: Dates--12.2.1 Simple dates----------------------Dates in the journal file use _simple dates_ format: 'YYYY-MM-DD' or-'YYYY/MM/DD' or 'YYYY.MM.DD', with leading zeros optional.  The year may-be omitted, in which case it will be inferred from the context: the-current transaction, the default year set with a default year directive,-or the current date when the command is run.  Some examples:-'2010-01-31', '2010/01/31', '2010.1.31', '1/31'.--   (The UI also accepts simple dates, as well as the more flexible smart-dates documented in the hledger manual.)---File: hledger.info,  Node: Secondary dates,  Next: Posting dates,  Prev: Simple dates,  Up: Dates--12.2.2 Secondary dates-------------------------Real-life transactions sometimes involve more than one date - eg the-date you write a cheque, and the date it clears in your bank.  When you-want to model this, for more accurate daily balances, you can specify-individual posting dates.--   Or, you can use the older _secondary date_ feature (Ledger calls it-auxiliary date or effective date).  Note: we support this for-compatibility, but I usually recommend avoiding this feature; posting-dates are almost always clearer and simpler.--   A secondary date is written after the primary date, following an-equals sign.  If the year is omitted, the primary date's year is-assumed.  When running reports, the primary (left) date is used by-default, but with the '--date2' flag (or '--aux-date' or '--effective'),-the secondary (right) date will be used instead.--   The meaning of secondary dates is up to you, but it's best to follow-a consistent rule.  Eg "primary = the bank's clearing date, secondary =-date the transaction was initiated, if different", as shown here:--2010/2/23=2/19 movie ticket-  expenses:cinema                   $10-  assets:checking--$ hledger register checking-2010-02-23 movie ticket         assets:checking                $-10         $-10--$ hledger register checking --date2-2010-02-19 movie ticket         assets:checking                $-10         $-10---File: hledger.info,  Node: Posting dates,  Prev: Secondary dates,  Up: Dates--12.2.3 Posting dates-----------------------You can give individual postings a different date from their parent-transaction, by adding a posting comment containing a tag (see below)-like 'date:DATE'.  This is probably the best way to control posting-dates precisely.  Eg in this example the expense should appear in May-reports, and the deduction from checking should be reported on 6/1 for-easy bank reconciliation:--2015/5/30-    expenses:food     $10  ; food purchased on saturday 5/30-    assets:checking        ; bank cleared it on monday, date:6/1--$ hledger -f t.j register food-2015-05-30                      expenses:food                  $10           $10--$ hledger -f t.j register checking-2015-06-01                      assets:checking               $-10          $-10--   DATE should be a simple date; if the year is not specified it will-use the year of the transaction's date.  You can set the secondary date-similarly, with 'date2:DATE2'.  The 'date:' or 'date2:' tags must have a-valid simple date value if they are present, eg a 'date:' tag with no-value is not allowed.--   Ledger's earlier, more compact bracketed date syntax is also-supported: '[DATE]', '[DATE=DATE2]' or '[=DATE2]'.  hledger will attempt-to parse any square-bracketed sequence of the '0123456789/-.='-characters in this way.  With this syntax, DATE infers its year from the-transaction and DATE2 infers its year from DATE.---File: hledger.info,  Node: Status,  Next: Code,  Prev: Dates,  Up: JOURNAL FORMAT--12.3 Status-===========--Transactions, or individual postings within a transaction, can have a-status mark, which is a single character before the transaction-description or posting account name, separated from it by a space,-indicating one of three statuses:--mark  status- -------------------      unmarked-'!'   pending-'*'   cleared--   When reporting, you can filter by status with the '-U/--unmarked',-'-P/--pending', and '-C/--cleared' flags; or the 'status:', 'status:!',-and 'status:*' queries; or the U, P, C keys in hledger-ui.--   Note, in Ledger and in older versions of hledger, the "unmarked"-state is called "uncleared".  As of hledger 1.3 we have renamed it to-unmarked for clarity.--   To replicate Ledger and old hledger's behaviour of also matching-pending, combine -U and -P.--   Status marks are optional, but can be helpful eg for reconciling with-real-world accounts.  Some editor modes provide highlighting and-shortcuts for working with status.  Eg in Emacs ledger-mode, you can-toggle transaction status with C-c C-e, or posting status with C-c C-c.--   What "uncleared", "pending", and "cleared" actually mean is up to-you.  Here's one suggestion:--status     meaning----------------------------------------------------------------------------uncleared  recorded but not yet reconciled; needs review-pending    tentatively reconciled (if needed, eg during a big-           reconciliation)-cleared    complete, reconciled as far as possible, and considered-           correct--   With this scheme, you would use '-PC' to see the current balance at-your bank, '-U' to see things which will probably hit your bank soon-(like uncashed checks), and no flags to see the most up-to-date state of-your finances.---File: hledger.info,  Node: Code,  Next: Description,  Prev: Status,  Up: JOURNAL FORMAT--12.4 Code-=========--After the status mark, but before the description, you can optionally-write a transaction "code", enclosed in parentheses.  This is a good-place to record a check number, or some other important transaction id-or reference number.---File: hledger.info,  Node: Description,  Next: Comments,  Prev: Code,  Up: JOURNAL FORMAT--12.5 Description-================--A transaction's description is the rest of the line following the date-and status mark (or until a comment begins).  Sometimes called the-"narration" in traditional bookkeeping, it can be used for whatever you-wish, or left blank.  Transaction descriptions can be queried, unlike-comments.--* Menu:--* Payee and note::---File: hledger.info,  Node: Payee and note,  Up: Description--12.5.1 Payee and note------------------------You can optionally include a '|' (pipe) character in descriptions to-subdivide the description into separate fields for payee/payer name on-the left (up to the first '|') and an additional note field on the right-(after the first '|').  This may be worthwhile if you need to do more-precise querying and pivoting by payee or by note.---File: hledger.info,  Node: Comments,  Next: Tags,  Prev: Description,  Up: JOURNAL FORMAT--12.6 Comments-=============--Lines in the journal beginning with a semicolon (';') or hash ('#') or-star ('*') are comments, and will be ignored.  (Star comments cause-org-mode nodes to be ignored, allowing emacs users to fold and navigate-their journals with org-mode or orgstruct-mode.)--   You can attach comments to a transaction by writing them after the-description and/or indented on the following lines (before the-postings).  Similarly, you can attach comments to an individual posting-by writing them after the amount and/or indented on the following lines.-Transaction and posting comments must begin with a semicolon (';').--   Some examples:--# a file comment-; another file comment-* also a file comment, useful in org/orgstruct mode--comment-A multiline file comment, which continues-until a line containing just "end comment"-(or end of file).-end comment--2012/5/14 something  ; a transaction comment-    ; the transaction comment, continued-    posting1  1  ; a comment for posting 1-    posting2-    ; a comment for posting 2-    ; another comment line for posting 2-; a file comment (because not indented)--   You can also comment larger regions of a file using 'comment' and-'end comment' directives.---File: hledger.info,  Node: Tags,  Next: Postings,  Prev: Comments,  Up: JOURNAL FORMAT--12.7 Tags-=========--Tags are a way to add extra labels or labelled data to postings and-transactions, which you can then search or pivot on.--   A simple tag is a word (which may contain hyphens) followed by a full-colon, written inside a transaction or posting comment line:--2017/1/16 bought groceries  ; sometag:--   Tags can have a value, which is the text after the colon, up to the-next comma or end of line, with leading/trailing whitespace removed:--    expenses:food    $10 ; a-posting-tag: the tag value--   Note this means hledger's tag values can not contain commas or-newlines.  Ending at commas means you can write multiple short tags on-one line, comma separated:--    assets:checking  ; a comment containing tag1:, tag2: some value ...--   Here,--   * "'a comment containing'" is just comment text, not a tag-   * "'tag1'" is a tag with no value-   * "'tag2'" is another tag, whose value is "'some value ...'"--   Tags in a transaction comment affect the transaction and all of its-postings, while tags in a posting comment affect only that posting.  For-example, the following transaction has three tags ('A', 'TAG2',-'third-tag') and the posting has four (those plus 'posting-tag'):--1/1 a transaction  ; A:, TAG2:-    ; third-tag: a third transaction tag, <- with a value-    (a)  $1  ; posting-tag:--   Tags are like Ledger's metadata feature, except hledger's tag values-are simple strings.---File: hledger.info,  Node: Postings,  Next: Account names,  Prev: Tags,  Up: JOURNAL FORMAT--12.8 Postings-=============--A posting is an addition of some amount to, or removal of some amount-from, an account.  Each posting line begins with at least one space or-tab (2 or 4 spaces is common), followed by:--   * (optional) a status character (empty, '!', or '*'), followed by a-     space-   * (required) an account name (any text, optionally containing *single-     spaces*, until end of line or a double space)-   * (optional) *two or more spaces* or tabs followed by an amount.--   Positive amounts are being added to the account, negative amounts are-being removed.--   The amounts within a transaction must always sum up to zero.  As a-convenience, one amount may be left blank; it will be inferred so as to-balance the transaction.--   Be sure to note the unusual two-space delimiter between account name-and amount.  This makes it easy to write account names containing-spaces.  But if you accidentally leave only one space (or tab) before-the amount, the amount will be considered part of the account name.--* Menu:--* Virtual postings::---File: hledger.info,  Node: Virtual postings,  Up: Postings--12.8.1 Virtual postings--------------------------A posting with a parenthesised account name is called a _virtual-posting_ or _unbalanced posting_, which means it is exempt from the-usual rule that a transaction's postings must balance add up to zero.--   This is not part of double entry accounting, so you might choose to-avoid this feature.  Or you can use it sparingly for certain special-cases where it can be convenient.  Eg, you could set opening balances-without using a balancing equity account:--1/1 opening balances-  (assets:checking)   $1000-  (assets:savings)    $2000--   A posting with a bracketed account name is called a _balanced virtual-posting_.  The balanced virtual postings in a transaction must add up to-zero (separately from other postings).  Eg:--1/1 buy food with cash, update budget envelope subaccounts, & something else-  assets:cash                    $-10 ; <- these balance-  expenses:food                    $7 ; <--  expenses:food                    $3 ; <--  [assets:checking:budget:food]  $-10    ; <- and these balance-  [assets:checking:available]     $10    ; <--  (something:else)                 $5       ; <- not required to balance--   Ordinary non-parenthesised, non-bracketed postings are called _real-postings_.  You can exclude virtual postings from reports with the-'-R/--real' flag or 'real:1' query.---File: hledger.info,  Node: Account names,  Next: Amounts,  Prev: Postings,  Up: JOURNAL FORMAT--12.9 Account names-==================--Account names typically have several parts separated by a full colon,-from which hledger derives a hierarchical chart of accounts.  They can-be anything you like, but in finance there are traditionally five-top-level accounts: 'assets', 'liabilities', 'revenue', 'expenses', and-'equity'.--   Account names may contain single spaces, eg: 'assets:accounts-receivable'.  Because of this, they must always be followed by *two or-more spaces* (or newline).--   Account names can be aliased.---File: hledger.info,  Node: Amounts,  Next: Transaction prices,  Prev: Account names,  Up: JOURNAL FORMAT--12.10 Amounts-=============--After the account name, there is usually an amount.  (Important: between-account name and amount, there must be *two or more spaces*.)--   hledger's amount format is flexible, supporting several international-formats.  Here are some examples.  Amounts have a number (the-"quantity"):--1--   ..and usually a currency symbol or commodity name (more on this-below), to the left or right of the quantity, with or without a-separating space:--$1-4000 AAPL-3 "green apples"--   Amounts can be preceded by a minus sign (or a plus sign, though plus-is the default), The sign can be written before or after a left-side-commodity symbol:---$1-$-1--   One or more spaces between the sign and the number are acceptable-when parsing (but they won't be displayed in output):--+ $1-$-      1--   Scientific E notation is allowed:--1E-6-EUR 1E3--* Menu:--* Decimal marks digit group marks::-* Commodity::-* Directives influencing number parsing and display::-* Commodity display style::-* Rounding::---File: hledger.info,  Node: Decimal marks digit group marks,  Next: Commodity,  Up: Amounts--12.10.1 Decimal marks, digit group marks-------------------------------------------A _decimal mark_ can be written as a period or a comma:--1.23-1,23456780000009--   In the integer part of the quantity (left of the decimal mark),-groups of digits can optionally be separated by a _digit group mark_ - a-space, comma, or period (different from the decimal mark):--     $1,000,000.00-  EUR 2.000.000,00-INR 9,99,99,999.00-      1 000 000.9455--   Note, a number containing a single digit group mark and no decimal-mark is ambiguous.  Are these digit group marks or decimal marks ?--1,000-1.000--   If you don't tell it otherwise, hledger will assume both of the above-are decimal marks, parsing both numbers as 1.--   To prevent confusing parsing mistakes and undetected typos,-especially if your data contains digit group marks (eg, thousands-separators), we recommend explicitly declaring the decimal mark-character in each journal file, using a directive at the top of the-file.  The 'decimal-mark' directive is best, otherwise 'commodity'-directives will also work.  These are described detail below.---File: hledger.info,  Node: Commodity,  Next: Directives influencing number parsing and display,  Prev: Decimal marks digit group marks,  Up: Amounts--12.10.2 Commodity--------------------Amounts in hledger have both a "quantity", which is a signed decimal-number, and a "commodity", which is a currency symbol, stock ticker, or-any word or phrase describing something you are tracking.--   If the commodity name contains non-letters (spaces, numbers, or-punctuation), you must always write it inside double quotes ('"green-apples"', '"ABC123"').--   If you write just a bare number, that too will have a commodity, with-name '""'; we call that the "no-symbol commodity".--   Actually, hledger combines these single-commodity amounts into more-powerful multi-commodity amounts, which are what it works with most of-the time.  A multi-commodity amount could be, eg: '1 USD, 2 EUR, 3.456-TSLA'.  In practice, you will only see multi-commodity amounts in-hledger's output; you can't write them directly in the journal file.--   (If you are writing scripts or working with hledger's internals,-these are the 'Amount' and 'MixedAmount' types.)---File: hledger.info,  Node: Directives influencing number parsing and display,  Next: Commodity display style,  Prev: Commodity,  Up: Amounts--12.10.3 Directives influencing number parsing and display------------------------------------------------------------You can add 'decimal-mark' and 'commodity' directives to the journal, to-declare and control these things more explicitly and precisely.  These-are described below, in JOURNAL FORMAT -> Declaring commodities.  Here's-a quick example:--# the decimal mark character used by all amounts in this file (all commodities)-decimal-mark .--# display styles for the $, EUR, INR and no-symbol commodities:-commodity $1,000.00-commodity EUR 1.000,00-commodity INR 9,99,99,999.00-commodity 1 000 000.9455---File: hledger.info,  Node: Commodity display style,  Next: Rounding,  Prev: Directives influencing number parsing and display,  Up: Amounts--12.10.4 Commodity display style----------------------------------For the amounts in each commodity, hledger chooses a consistent display-style to use in most reports.  (Exceptions: price amounts, and all-amounts displayed by the 'print' command, are displayed with all of-their decimal digits visible.)--   A commodity's display style is inferred as follows.--   First, if a default commodity is declared with 'D', this commodity-and its style is applied to any no-symbol amounts in the journal.--   Then each commodity's style is inferred from one of the following, in-order of preference:--   * The commodity directive for that commodity (including the no-symbol-     commodity), if any.-   * The amounts in that commodity seen in the journal's transactions.-     (Posting amounts only; prices and periodic or auto rules are-     ignored, currently.)-   * The built-in fallback style, which looks like this: '$1000.00'.-     (Symbol on the left, period decimal mark, two decimal places.)--   A style is inferred from journal amounts as follows:--   * Use the general style (decimal mark, symbol placement) of the first-     amount-   * Use the first-seen digit group style (digit group mark, digit group-     sizes), if any-   * Use the maximum number of decimal places of all.--   Transaction price amounts don't affect the commodity display style-directly, but occasionally they can do so indirectly (eg when a-posting's amount is inferred using a transaction price).  If you find-this causing problems, use a commodity directive to fix the display-style.--   To summarise: each commodity's amounts will be normalised to (a) the-style declared by a 'commodity' directive, or (b) the style of the first-posting amount in the journal, with the first-seen digit group style and-the maximum-seen number of decimal places.  So if your reports are-showing amounts in a way you don't like, eg with too many decimal-places, use a commodity directive.  Some examples:--# declare euro, dollar, bitcoin and no-symbol commodities and set their -# input number formats and output display styles:-commodity EUR 1.000,-commodity $1000.00-commodity 1000.00000000 BTC-commodity 1 000.--   The inferred commodity style can be overridden by supplying a command-line option.---File: hledger.info,  Node: Rounding,  Prev: Commodity display style,  Up: Amounts--12.10.5 Rounding-------------------Amounts are stored internally as decimal numbers with up to 255 decimal-places, and displayed with the number of decimal places specified by the-commodity display style.  Note, hledger uses banker's rounding: it-rounds to the nearest even number, eg 0.5 displayed with zero decimal-places is "0").  (Guaranteed since hledger 1.17.1; in older versions-this could vary if hledger was built with Decimal < 0.5.1.)---File: hledger.info,  Node: Transaction prices,  Next: Lot prices lot dates,  Prev: Amounts,  Up: JOURNAL FORMAT--12.11 Transaction prices-========================--Within a transaction, you can note an amount's price in another-commodity.  This can be used to document the cost (in a purchase) or-selling price (in a sale).  For example, transaction prices are useful-to record purchases of a foreign currency.  Note transaction prices are-fixed at the time of the transaction, and do not change over time.  See-also market prices, which represent prevailing exchange rates on a-certain date.--   There are several ways to record a transaction price:--  1. Write the price per unit, as '@ UNITPRICE' after the amount:--     2009/1/1-       assets:euros     €100 @ $1.35  ; one hundred euros purchased at $1.35 each-       assets:dollars                 ; balancing amount is -$135.00--  2. Write the total price, as '@@ TOTALPRICE' after the amount:--     2009/1/1-       assets:euros     €100 @@ $135  ; one hundred euros purchased at $135 for the lot-       assets:dollars--  3. Specify amounts for all postings, using exactly two commodities,-     and let hledger infer the price that balances the transaction:--     2009/1/1-       assets:euros     €100          ; one hundred euros purchased-       assets:dollars  $-135          ; for $135--  4. Like 1, but the '@' is parenthesised, i.e.  '(@)'; this is for-     compatibility with Ledger journals (Virtual posting costs), and is-     equivalent to 1 in hledger.--  5. Like 2, but as in 4 the '@@' is parenthesised, i.e.  '(@@)'; in-     hledger, this is equivalent to 2.--   Use the '-B/--cost' flag to convert amounts to their transaction-price's commodity, if any.  (mnemonic: "B" is from "cost Basis", as in-Ledger).  Eg here is how -B affects the balance report for the example-above:--$ hledger bal -N --flat-               $-135  assets:dollars-                €100  assets:euros-$ hledger bal -N --flat -B-               $-135  assets:dollars-                $135  assets:euros    # <- the euros' cost--   Note -B is sensitive to the order of postings when a transaction-price is inferred: the inferred price will be in the commodity of the-last amount.  So if example 3's postings are reversed, while the-transaction is equivalent, -B shows something different:--2009/1/1-  assets:dollars  $-135              ; 135 dollars sold-  assets:euros     €100              ; for 100 euros--$ hledger bal -N --flat -B-               €-100  assets:dollars  # <- the dollars' selling price-                €100  assets:euros---File: hledger.info,  Node: Lot prices lot dates,  Next: Balance assertions,  Prev: Transaction prices,  Up: JOURNAL FORMAT--12.12 Lot prices, lot dates-===========================--Ledger allows another kind of price, lot price (four variants:-'{UNITPRICE}', '{{TOTALPRICE}}', '{=FIXEDUNITPRICE}',-'{{=FIXEDTOTALPRICE}}'), and/or a lot date ('[DATE]') to be specified.-These are normally used to select a lot when selling investments.-hledger will parse these, for compatibility with Ledger journals, but-currently ignores them.  A transaction price, lot price and/or lot date-may appear in any order, after the posting amount and before the balance-assertion if any.---File: hledger.info,  Node: Balance assertions,  Next: Balance assignments,  Prev: Lot prices lot dates,  Up: JOURNAL FORMAT--12.13 Balance assertions-========================--hledger supports Ledger-style balance assertions in journal files.-These look like, for example, '= EXPECTEDBALANCE' following a posting's-amount.  Eg here we assert the expected dollar balance in accounts a and-b after each posting:--2013/1/1-  a   $1  =$1-  b       =$-1--2013/1/2-  a   $1  =$2-  b  $-1  =$-2--   After reading a journal file, hledger will check all balance-assertions and report an error if any of them fail.  Balance assertions-can protect you from, eg, inadvertently disrupting reconciled balances-while cleaning up old entries.  You can disable them temporarily with-the '-I/--ignore-assertions' flag, which can be useful for-troubleshooting or for reading Ledger files.  (Note: this flag currently-does not disable balance assignments, below).--* Menu:--* Assertions and ordering::-* Assertions and included files::-* Assertions and multiple -f options::-* Assertions and commodities::-* Assertions and prices::-* Assertions and subaccounts::-* Assertions and virtual postings::-* Assertions and precision::---File: hledger.info,  Node: Assertions and ordering,  Next: Assertions and included files,  Up: Balance assertions--12.13.1 Assertions and ordering----------------------------------hledger sorts an account's postings and assertions first by date and-then (for postings on the same day) by parse order.  Note this is-different from Ledger, which sorts assertions only by parse order.-(Also, Ledger assertions do not see the accumulated effect of repeated-postings to the same account within a transaction.)--   So, hledger balance assertions keep working if you reorder-differently-dated transactions within the journal.  But if you reorder-same-dated transactions or postings, assertions might break and require-updating.  This order dependence does bring an advantage: precise-control over the order of postings and assertions within a day, so you-can assert intra-day balances.---File: hledger.info,  Node: Assertions and included files,  Next: Assertions and multiple -f options,  Prev: Assertions and ordering,  Up: Balance assertions--12.13.2 Assertions and included files----------------------------------------With included files, things are a little more complicated.  Including-preserves the ordering of postings and assertions.  If you have multiple-postings to an account on the same day, split across different files,-and you also want to assert the account's balance on the same day,-you'll have to put the assertion in the right file.---File: hledger.info,  Node: Assertions and multiple -f options,  Next: Assertions and commodities,  Prev: Assertions and included files,  Up: Balance assertions--12.13.3 Assertions and multiple -f options---------------------------------------------Balance assertions don't work well across files specified with multiple--f options.  Use include or concatenate the files instead.---File: hledger.info,  Node: Assertions and commodities,  Next: Assertions and prices,  Prev: Assertions and multiple -f options,  Up: Balance assertions--12.13.4 Assertions and commodities-------------------------------------The asserted balance must be a simple single-commodity amount, and in-fact the assertion checks only this commodity's balance within the-(possibly multi-commodity) account balance.  This is how assertions work-in Ledger also.  We could call this a "partial" balance assertion.--   To assert the balance of more than one commodity in an account, you-can write multiple postings, each asserting one commodity's balance.--   You can make a stronger "total" balance assertion by writing a double-equals sign ('== EXPECTEDBALANCE').  This asserts that there are no-other unasserted commodities in the account (or, that their balance is-0).--2013/1/1-  a   $1-  a    1€-  b  $-1-  c   -1€--2013/1/2  ; These assertions succeed-  a    0  =  $1-  a    0  =   1€-  b    0 == $-1-  c    0 ==  -1€--2013/1/3  ; This assertion fails as 'a' also contains 1€-  a    0 ==  $1--   It's not yet possible to make a complete assertion about a balance-that has multiple commodities.  One workaround is to isolate each-commodity into its own subaccount:--2013/1/1-  a:usd   $1-  a:euro   1€-  b--2013/1/2-  a        0 ==  0-  a:usd    0 == $1-  a:euro   0 ==  1€---File: hledger.info,  Node: Assertions and prices,  Next: Assertions and subaccounts,  Prev: Assertions and commodities,  Up: Balance assertions--12.13.5 Assertions and prices--------------------------------Balance assertions ignore transaction prices, and should normally be-written without one:--2019/1/1-  (a)     $1 @ €1 = $1--   We do allow prices to be written there, however, and print shows-them, even though they don't affect whether the assertion passes or-fails.  This is for backward compatibility (hledger's close command used-to generate balance assertions with prices), and because balance-_assignments_ do use them (see below).---File: hledger.info,  Node: Assertions and subaccounts,  Next: Assertions and virtual postings,  Prev: Assertions and prices,  Up: Balance assertions--12.13.6 Assertions and subaccounts-------------------------------------The balance assertions above ('=' and '==') do not count the balance-from subaccounts; they check the account's exclusive balance only.  You-can assert the balance including subaccounts by writing '=*' or '==*',-eg:--2019/1/1-  equity:opening balances-  checking:a       5-  checking:b       5-  checking         1  ==* 11---File: hledger.info,  Node: Assertions and virtual postings,  Next: Assertions and precision,  Prev: Assertions and subaccounts,  Up: Balance assertions--12.13.7 Assertions and virtual postings------------------------------------------Balance assertions are checked against all postings, both real and-virtual.  They are not affected by the '--real/-R' flag or 'real:'-query.---File: hledger.info,  Node: Assertions and precision,  Prev: Assertions and virtual postings,  Up: Balance assertions--12.13.8 Assertions and precision-----------------------------------Balance assertions compare the exactly calculated amounts, which are not-always what is shown by reports.  Eg a commodity directive may limit the-display precision, but this will not affect balance assertions.  Balance-assertion failure messages show exact amounts.---File: hledger.info,  Node: Balance assignments,  Next: Directives,  Prev: Balance assertions,  Up: JOURNAL FORMAT--12.14 Balance assignments-=========================--Ledger-style balance assignments are also supported.  These are like-balance assertions, but with no posting amount on the left side of the-equals sign; instead it is calculated automatically so as to satisfy the-assertion.  This can be a convenience during data entry, eg when setting-opening balances:--; starting a new journal, set asset account balances-2016/1/1 opening balances-  assets:checking            = $409.32-  assets:savings             = $735.24-  assets:cash                 = $42-  equity:opening balances--   or when adjusting a balance to reality:--; no cash left; update balance, record any untracked spending as a generic expense-2016/1/15-  assets:cash    = $0-  expenses:misc--   The calculated amount depends on the account's balance in the-commodity at that point (which depends on the previously-dated postings-of the commodity to that account since the last balance assertion or-assignment).  Note that using balance assignments makes your journal a-little less explicit; to know the exact amount posted, you have to run-hledger or do the calculations yourself, instead of just reading it.--* Menu:--* Balance assignments and prices::---File: hledger.info,  Node: Balance assignments and prices,  Up: Balance assignments--12.14.1 Balance assignments and prices-----------------------------------------A transaction price in a balance assignment will cause the calculated-amount to have that price attached:--2019/1/1-  (a)             = $1 @ €2--$ hledger print --explicit-2019-01-01-    (a)         $1 @ €2 = $1 @ €2---File: hledger.info,  Node: Directives,  Next: Directives and multiple files,  Prev: Balance assignments,  Up: JOURNAL FORMAT--12.15 Directives-================--A directive is a line in the journal beginning with a special keyword,-that influences how the journal is processed, how things are displayed,-and so on.  hledger's directives are based on (a subset of) Ledger's,-but there are many differences, and also some differences between-hledger versions.  Here are some more definitions:--   * _subdirective_ - Some directives support subdirectives, written-     indented below the parent directive.--   * _decimal mark_ - The character to interpret as a decimal mark-     (period or comma) when parsing amounts of a commodity.--   * _display style_ - How to display amounts of a commodity in output:-     symbol side and spacing, digit groups, decimal mark, and number of-     decimal places.--   Directives are not required when starting out with hledger, but you-will probably add some as your needs grow.  Here is an overview of-directives by purpose:--purpose                          directives             command line-                                                        options with-                                                        similar effect-----------------------------------------------------------------------------*READING/GENERATING DATA:*-Declare a commodity's or         'commodity', 'D',-file's decimal mark to help      'decimal-mark'-parse amounts accurately-Apply changes to the data        'alias', 'apply        '--alias'-while parsing                    account', 'comment',-                                 'D', 'Y'-Inline extra data files          'include'              multiple-                                                        '-f/--file''s-Generate extra transactions or   '~'-budget goals-Generate extra postings          '='-*CHECKING FOR ERRORS:*-Define valid entities to allow   'account',-stricter error checking          'commodity', 'payee'-*DISPLAYING REPORTS:*-Declare accounts' display        'account'-order and accounting type-Declare commodity display        'commodity', 'D'       '-c/--commodity-style'-styles--   And here are all the directives and their precise effects:--directiveeffects                                                      ends-                                                                      at-                                                                      file-                                                                      end?-----------------------------------------------------------------------------*'account'*Declares an account, for checking all entries in all files;-      and its display order and type, for reports.  Subdirectives:-      any text, ignored.-*'alias'*Rewrites account names, in following entries until end of    Y-      current file or 'end aliases'.-*'applyPrepends a common parent account to all account names, in      Y-account'*following entries until end of current file or 'end apply-      account'.-*'comment'*Ignores part of the journal file, until end of current fileY-      or 'end comment'.-*'commodity'*Declares a commodity, for checking all entries in all files;N,-      the decimal mark for parsing amounts of this commodity, for     Y-      following entries until end of current file; and its display-      style, for reports.  Takes precedence over 'D'.-      Subdirectives: 'format' (alternate syntax).-*'D'* Sets a default commodity to use for no-symbol amounts, and      Y-      its decimal mark for parsing amounts of this commodity in-      following entries until end of current file; and its display-      style, for reports.-*'decimal-mark'*Declares the decimal mark, for parsing amounts of all Y-      commodities in following entries until next 'decimal-mark' or-      end of current file.  Included files can override.  Takes-      precedence over 'commodity' and 'D'.-*'include'*Includes entries and directives from another file, as if they-      were written inline.-*'payee'*Declares a payee name, for checking all entries in all files.-*'P'* Declares a market price for a commodity on some date, for-      valuation reports.-*'Y'* Declares a year for yearless dates, for following entries       Y-      until end of current file.-*'~'* Declares a periodic transaction rule that generates future-(tilde)transactions with '--forecast' and budget goals with 'balance-      --budget'.-*'='* Declares an auto posting rule that generates extra postings     partly-(equals)on matched transactions with '--auto', in current, parent,-      and child files (but not sibling files, see #1212).---File: hledger.info,  Node: Directives and multiple files,  Next: Comment blocks,  Prev: Directives,  Up: JOURNAL FORMAT--12.16 Directives and multiple files-===================================--If you use multiple '-f'/'--file' options, or the 'include' directive,-hledger will process multiple input files.  But directives which affect-input typically have effect only until the end of the file in which they-occur (and on any included files in that region).--   This may seem inconvenient, but it's intentional; it makes reports-stable and deterministic, independent of the order of input.  Otherwise-you could see different numbers if you happened to write -f options in a-different order, or if you moved includes around while cleaning up your-files.--   It can be surprising though; for example, it means that 'alias'-directives do not affect parent or sibling files (see below).---File: hledger.info,  Node: Comment blocks,  Next: Including other files,  Prev: Directives and multiple files,  Up: JOURNAL FORMAT--12.17 Comment blocks-====================--A line containing just 'comment' starts a commented region of the file,-and a line containing just 'end comment' (or the end of the current-file) ends it.  See also comments.---File: hledger.info,  Node: Including other files,  Next: Default year,  Prev: Comment blocks,  Up: JOURNAL FORMAT--12.18 Including other files-===========================--You can pull in the content of additional files by writing an include-directive, like this:--include FILEPATH--   Only journal files can include, and only journal, timeclock or-timedot files can be included (not CSV files, currently).--   If the file path does not begin with a slash, it is relative to the-current file's folder.--   A tilde means home directory, eg: 'include ~/main.journal'.--   The path may contain glob patterns to match multiple files, eg:-'include *.journal'.--   There is limited support for recursive wildcards: '**/' (the slash is-required) matches 0 or more subdirectories.  It's not super convenient-since you have to avoid include cycles and including directories, but-this can be done, eg: 'include */**/*.journal'.--   The path may also be prefixed to force a specific file format,-overriding the file extension (as described in hledger.1 -> Input-files): 'include timedot:~/notes/2020*.md'.---File: hledger.info,  Node: Default year,  Next: Declaring payees,  Prev: Including other files,  Up: JOURNAL FORMAT--12.19 Default year-==================--You can set a default year to be used for subsequent dates which don't-specify a year.  This is a line beginning with 'Y' followed by the year.-Eg:--Y2009  ; set default year to 2009--12/15  ; equivalent to 2009/12/15-  expenses  1-  assets--Y2010  ; change default year to 2010--2009/1/30  ; specifies the year, not affected-  expenses  1-  assets--1/31   ; equivalent to 2010/1/31-  expenses  1-  assets---File: hledger.info,  Node: Declaring payees,  Next: Declaring the decimal mark,  Prev: Default year,  Up: JOURNAL FORMAT--12.20 Declaring payees-======================--The 'payee' directive can be used to declare a limited set of payees-which may appear in transaction descriptions.  The "payees" check will-report an error if any transaction refers to a payee that has not been-declared.  Eg:--payee Whole Foods---File: hledger.info,  Node: Declaring the decimal mark,  Next: Declaring commodities,  Prev: Declaring payees,  Up: JOURNAL FORMAT--12.21 Declaring the decimal mark-================================--You can use a 'decimal-mark' directive - usually one per file, at the-top of the file - to declare which character represents a decimal mark-when parsing amounts in this file.  It can look like--decimal-mark .--   or--decimal-mark ,--   This prevents any ambiguity when parsing numbers in the file, so we-recommend it, especially if the file contains digit group marks (eg-thousands separators).---File: hledger.info,  Node: Declaring commodities,  Next: Default commodity,  Prev: Declaring the decimal mark,  Up: JOURNAL FORMAT--12.22 Declaring commodities-===========================--You can use 'commodity' directives to declare your commodities.  In fact-the 'commodity' directive performs several functions at once:--  1. It declares commodities which may be used in the journal.  This can-     optionally be enforced, providing useful error checking.  (Cf-     Commodity error checking)--  2. It declares which decimal mark character (period or comma), to-     expect when parsing input - useful to disambiguate international-     number formats in your data.  Without this, hledger will parse both-     '1,000' and '1.000' as 1.  (Cf Amounts)--  3. It declares how to render the commodity's amounts when displaying-     output - the decimal mark, any digit group marks, the number of-     decimal places, symbol placement and so on.  (Cf Commodity display-     style)--   You will run into one of the problems solved by commodity directives-sooner or later, so we recommend using them, for robust and predictable-parsing and display.--   Generally you should put them at the top of your journal file (since-for function 2, they affect only following amounts, cf #793).--   A commodity directive is just the word 'commodity' followed by a-sample amount, like this:--;commodity SAMPLEAMOUNT--commodity $1000.00-commodity 1,000.0000 AAAA  ; optional same-line comment--   It may also be written on multiple lines, and use the 'format'-subdirective, as in Ledger.  Note in this case the commodity symbol-appears twice; it must be the same in both places:--;commodity SYMBOL-;  format SAMPLEAMOUNT--; display indian rupees with currency name on the left,-; thousands, lakhs and crores comma-separated,-; period as decimal point, and two decimal places.-commodity INR-  format INR 1,00,00,000.00--   Remember that if the commodity symbol contains spaces, numbers, or-punctuation, it must be enclosed in double quotes (cf Commodity).--   The amount's quantity does not matter; only the format is-significant.  It must include a decimal mark - either a period or a-comma - followed by 0 or more decimal digits.--   A few more examples:--# number formats for $, EUR, INR and the no-symbol commodity:-commodity $1,000.00-commodity EUR 1.000,00-commodity INR 9,99,99,999.0-commodity 1 000 000.--   Note hledger normally uses banker's rounding, so 0.5 displayed with-zero decimal digits is "0".  (More at Commodity display style.)--   Even in the presence of commodity directives, the commodity display-style can still be overridden by supplying a command line option.--* Menu:--* Commodity error checking::---File: hledger.info,  Node: Commodity error checking,  Up: Declaring commodities--12.22.1 Commodity error checking-----------------------------------In strict mode, enabled with the '-s'/'--strict' flag, hledger will-report an error if a commodity symbol is used that has not been declared-by a 'commodity' directive.  This works similarly to account error-checking, see the notes there for more details.---File: hledger.info,  Node: Default commodity,  Next: Declaring market prices,  Prev: Declaring commodities,  Up: JOURNAL FORMAT--12.23 Default commodity-=======================--The 'D' directive sets a default commodity, to be used for any-subsequent commodityless amounts (ie, plain numbers) seen while parsing-the journal.  This effect lasts until the next 'D' directive, or the end-of the journal.--   For compatibility/historical reasons, 'D' also acts like a-'commodity' directive (setting the commodity's decimal mark for parsing-and display style for output).--   The syntax is 'D AMOUNT'.  As with 'commodity', the amount must-include a decimal mark (either period or comma).  Eg:--; commodity-less amounts should be treated as dollars-; (and displayed with the dollar sign on the left, thousands separators and two decimal places)-D $1,000.00--1/1-  a     5  ; <- commodity-less amount, parsed as $5 and displayed as $5.00-  b--   If both 'commodity' and 'D' directives are found for a commodity,-'commodity' takes precedence for setting decimal mark and display style.--   If you are using 'D' and also checking commodities, you will need to-add a 'commodity' directive similar to the 'D'.  (The 'hledger check-commodities' command expects 'commodity' directives, and ignores 'D').---File: hledger.info,  Node: Declaring market prices,  Next: Declaring accounts,  Prev: Default commodity,  Up: JOURNAL FORMAT--12.24 Declaring market prices-=============================--The 'P' directive declares a market price, which is an exchange rate-between two commodities on a certain date.  (In Ledger, they are called-"historical prices".)  These are often obtained from a stock exchange,-cryptocurrency exchange, or the foreign exchange market.--   The format is:--P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT--   DATE is a simple date, COMMODITY1SYMBOL is the symbol of the-commodity being priced, and COMMODITY2AMOUNT is the amount (symbol and-quantity) of commodity 2 that one unit of commodity 1 is worth on this-date.  Examples:--# one euro was worth $1.35 from 2009-01-01 onward:-P 2009-01-01 € $1.35--# and $1.40 from 2010-01-01 onward:-P 2010-01-01 € $1.40--   The '-V', '-X' and '--value' flags use these market prices to show-amount values in another commodity.  See Valuation.---File: hledger.info,  Node: Declaring accounts,  Next: Rewriting accounts,  Prev: Declaring market prices,  Up: JOURNAL FORMAT--12.25 Declaring accounts-========================--'account' directives can be used to declare accounts (ie, the places-that amounts are transferred from and to).  Though not required, these-declarations can provide several benefits:--   * They can document your intended chart of accounts, providing a-     reference.-   * They can help hledger know your accounts' types (asset, liability,-     equity, revenue, expense), useful for reports like balancesheet and-     incomestatement.-   * They control account display order in reports, allowing-     non-alphabetic sorting (eg Revenues to appear above Expenses).-   * They can store extra information about accounts (account numbers,-     notes, etc.)-   * They help with account name completion in the add command,-     hledger-iadd, hledger-web, ledger-mode etc.-   * In strict mode, they restrict which accounts may be posted to by-     transactions, which helps detect typos.--   The simplest form is just the word 'account' followed by a-hledger-style account name, eg this account directive declares the-'assets:bank:checking' account:--account assets:bank:checking--* Menu:--* Account error checking::-* Account comments::-* Account subdirectives::-* Account types::-* Account display order::---File: hledger.info,  Node: Account error checking,  Next: Account comments,  Up: Declaring accounts--12.25.1 Account error checking---------------------------------By default, accounts come into existence when a transaction references-them by name.  This is convenient, but it means hledger can't warn you-when you mis-spell an account name in the journal.  Usually you'll find-the error later, as an extra account in balance reports, or an incorrect-balance when reconciling.--   In strict mode, enabled with the '-s'/'--strict' flag, hledger will-report an error if any transaction uses an account name that has not-been declared by an account directive.  Some notes:--   * The declaration is case-sensitive; transactions must use the-     correct account name capitalisation.-   * The account directive's scope is "whole file and below" (see-     directives).  This means it affects all of the current file, and-     any files it includes, but not parent or sibling files.  The-     position of account directives within the file does not matter,-     though it's usual to put them at the top.-   * Accounts can only be declared in 'journal' files (but will affect-     included files in other formats).-   * It's currently not possible to declare "all possible subaccounts"-     with a wildcard; every account posted to must be declared.---File: hledger.info,  Node: Account comments,  Next: Account subdirectives,  Prev: Account error checking,  Up: Declaring accounts--12.25.2 Account comments---------------------------Comments, beginning with a semicolon, can be added:--   * on the same line, *after two or more spaces* (because ; is allowed-     in account names)-   * on the next lines, indented--   An example of both:--account assets:bank:checking  ; same-line comment, note 2+ spaces before ;-  ; next-line comment-  ; another with tag, acctno:12345 (not used yet)--   Same-line comments are not supported by Ledger, or hledger <1.13.---File: hledger.info,  Node: Account subdirectives,  Next: Account types,  Prev: Account comments,  Up: Declaring accounts--12.25.3 Account subdirectives--------------------------------We also allow (and ignore) Ledger-style indented subdirectives, just for-compatibility.:--account assets:bank:checking-  format blah blah  ; <- subdirective, ignored--   Here is the full syntax of account directives:--account ACCTNAME  [ACCTTYPE] [;COMMENT]-  [;COMMENTS]-  [LEDGER-STYLE SUBDIRECTIVES, IGNORED]---File: hledger.info,  Node: Account types,  Next: Account display order,  Prev: Account subdirectives,  Up: Declaring accounts--12.25.4 Account types------------------------By adding a 'type' tag to the account directive, with value 'A', 'L',-'E', 'R', 'X', 'C' (or if you prefer: 'Asset', 'Liability', 'Equity',-'Revenue', 'Expense', 'Cash'), you can declare hledger accounts to be of-a certain type:--   * *asset*, *liability*, *equity*, *revenue*, *expense*-     the standard types in accounting, or--   * *cash*-     a subtype of asset, used for liquid assets.--   Declaring account types is a good idea, since it helps enable the-easy balancesheet, balancesheetequity, incomestatement and cashflow-reports, and probably other things in future.  As a convenience, when-account types are not declared, hledger will try to guess them based on-english-language account names.--   Here is a typical set of top-level account declarations (because of-the aforementioned, with these account names the type tags are not-strictly needed, but with non-english or non-standard account names,-they will be):--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--   It's not necessary to declare the type of subaccounts.  (You can, if-they are different from the parent, but this is not common.)--* Menu:--* Auto-detected account types::---File: hledger.info,  Node: Auto-detected account types,  Up: Account types--12.25.4.1 Auto-detected account types-.....................................--More about "guessing" account types: hledger tries to find at least one-top level account in each of the six account types (Asset, Liability,-Equity, Revenue, Expense, Cash).  When no accounts have been declared-for a particular type, it tries to auto-detect some accounts by name,-using the regular expressions below.  Note: if you declare any account's-type, it's a good idea to declare an account for all six types, because-a mix of declared and auto-detected types can cause confusing results.--   The auto-detection rules are:-- If account's name matches this case insensitive regular expression:| its type is:-------------------------------------------------------------------- | ------------- ^assets?(:|$)                                                      | -   and does not contain regexp (investment|receivable|:A/R|:fixed)  | Cash-   otherwise                                                        | Asset- ^(debts?|liabilit(y|ies))(:|$)                                     | Liability- ^equity(:|$)                                                       | Equity- ^(income|revenue)s?(:|$)                                           | Revenue- ^expenses?(:|$)                                                    | Expense---File: hledger.info,  Node: Account display order,  Prev: Account types,  Up: Declaring accounts--12.25.5 Account display order--------------------------------Account directives also set the order in which accounts are displayed,-eg in reports, the hledger-ui accounts screen, and the hledger-web-sidebar.  By default accounts are listed in alphabetical order.  But if-you have these account directives in the journal:--account assets-account liabilities-account equity-account revenues-account expenses--   you'll see those accounts displayed in declaration order, not-alphabetically:--$ hledger accounts -1-assets-liabilities-equity-revenues-expenses--   Undeclared accounts, if any, are displayed last, in alphabetical-order.--   Note that sorting is done at each level of the account tree (within-each group of sibling accounts under the same parent).  And currently,-this directive:--account other:zoo--   would influence the position of 'zoo' among 'other''s subaccounts,-but not the position of 'other' among the top-level accounts.  This-means:--   * you will sometimes declare parent accounts (eg 'account other'-     above) that you don't intend to post to, just to customize their-     display order-   * sibling accounts stay together (you couldn't display 'x:y' in-     between 'a:b' and 'a:c').---File: hledger.info,  Node: Rewriting accounts,  Next: Default parent account,  Prev: Declaring accounts,  Up: JOURNAL FORMAT--12.26 Rewriting accounts-========================--You can define account alias rules which rewrite your account names, or-parts of them, before generating reports.  This can be useful for:--   * expanding shorthand account names to their full form, allowing-     easier data entry and a less verbose journal-   * adapting old journals to your current chart of accounts-   * experimenting with new account organisations, like a new hierarchy-     or combining two accounts into one-   * customising reports--   Account aliases also rewrite account names in account directives.-They do not affect account names being entered via hledger add or-hledger-web.--   See also Rewrite account names.--* Menu:--* Basic aliases::-* Regex aliases::-* Combining aliases::-* Aliases and multiple files::-* end aliases::---File: hledger.info,  Node: Basic aliases,  Next: Regex aliases,  Up: Rewriting accounts--12.26.1 Basic aliases------------------------To set an account alias, use the 'alias' directive in your journal file.-This affects all subsequent journal entries in the current file or its-included files (but note: not sibling or parent files).  The spaces-around the = are optional:--alias OLD = NEW--   Or, you can use the '--alias 'OLD=NEW'' option on the command line.-This affects all entries.  It's useful for trying out aliases-interactively.--   OLD and NEW are case sensitive full account names.  hledger will-replace any occurrence of the old account name with the new one.-Subaccounts are also affected.  Eg:--alias checking = assets:bank:wells fargo:checking-; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"---File: hledger.info,  Node: Regex aliases,  Next: Combining aliases,  Prev: Basic aliases,  Up: Rewriting accounts--12.26.2 Regex aliases------------------------There is also a more powerful variant that uses a regular expression,-indicated by the forward slashes:--alias /REGEX/ = REPLACEMENT--   or '--alias '/REGEX/=REPLACEMENT''.--   REGEX is a case-insensitive regular expression.  Anywhere it matches-inside an account name, the matched part will be replaced by-REPLACEMENT. If REGEX contains parenthesised match groups, these can be-referenced by the usual numeric backreferences in REPLACEMENT. Eg:--alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3-; rewrites "assets:bank:wells fargo:checking" to  "assets:wells fargo checking"--   Also note that REPLACEMENT continues to the end of line (or on-command line, to end of option argument), so it can contain trailing-whitespace.---File: hledger.info,  Node: Combining aliases,  Next: Aliases and multiple files,  Prev: Regex aliases,  Up: Rewriting accounts--12.26.3 Combining aliases----------------------------You can define as many aliases as you like, using journal directives-and/or command line options.--   Recursive aliases - where an account name is rewritten by one alias,-then by another alias, and so on - are allowed.  Each alias sees the-effect of previously applied aliases.--   In such cases it can be important to understand which aliases will be-applied and in which order.  For (each account name in) each journal-entry, we apply:--  1. 'alias' directives preceding the journal entry, most recently-     parsed first (ie, reading upward from the journal entry, bottom to-     top)-  2. '--alias' options, in the order they appeared on the command line-     (left to right).--   In other words, for (an account name in) a given journal entry:--   * the nearest alias declaration before/above the entry is applied-     first-   * the next alias before/above that will be be applied next, and so on-   * aliases defined after/below the entry do not affect it.--   This gives nearby aliases precedence over distant ones, and helps-provide semantic stability - aliases will keep working the same way-independent of which files are being read and in which order.--   In case of trouble, adding '--debug=6' to the command line will show-which aliases are being applied when.---File: hledger.info,  Node: Aliases and multiple files,  Next: end aliases,  Prev: Combining aliases,  Up: Rewriting accounts--12.26.4 Aliases and multiple files-------------------------------------As explained at Directives and multiple files, 'alias' directives do not-affect parent or sibling files.  Eg in this command,--hledger -f a.aliases -f b.journal--   account aliases defined in a.aliases will not affect b.journal.-Including the aliases doesn't work either:--include a.aliases--2020-01-01  ; not affected by a.aliases-  foo  1-  bar--   This means that account aliases should usually be declared at the-start of your top-most file, like this:--alias foo=Foo-alias bar=Bar--2020-01-01  ; affected by aliases above-  foo  1-  bar--include c.journal  ; also affected---File: hledger.info,  Node: end aliases,  Prev: Aliases and multiple files,  Up: Rewriting accounts--12.26.5 'end aliases'------------------------You can clear (forget) all currently defined aliases (seen in the-journal so far, or defined on the command line) with this directive:--end aliases---File: hledger.info,  Node: Default parent account,  Next: Periodic transactions,  Prev: Rewriting accounts,  Up: JOURNAL FORMAT--12.27 Default parent account-============================--You can specify a parent account which will be prepended to all accounts-within a section of the journal.  Use the 'apply account' and 'end apply-account' directives like so:--apply account home--2010/1/1-    food    $10-    cash--end apply account--   which is equivalent to:--2010/01/01-    home:food           $10-    home:cash          $-10--   If 'end apply account' is omitted, the effect lasts to the end of the-file.  Included files are also affected, eg:--apply account business-include biz.journal-end apply account-apply account personal-include personal.journal--   Prior to hledger 1.0, legacy 'account' and 'end' spellings were also-supported.--   A default parent account also affects account directives.  It does-not affect account names being entered via hledger add or hledger-web.-If account aliases are present, they are applied after the default-parent account.---File: hledger.info,  Node: Periodic transactions,  Next: Auto postings,  Prev: Default parent account,  Up: JOURNAL FORMAT--12.28 Periodic transactions-===========================--Periodic transaction rules describe transactions that recur.  They allow-hledger to generate temporary future transactions to help with-forecasting, so you don't have to write out each one in the journal, and-it's easy to try out different forecasts.--   Periodic transactions can be a little tricky, so before you use them,-read this whole section - or at least these tips:--  1. Two spaces accidentally added or omitted will cause you trouble --     read about this below.-  2. For troubleshooting, show the generated transactions with 'hledger-     print --forecast tag:generated' or 'hledger register --forecast-     tag:generated'.-  3. Forecasted transactions will begin only after the last-     non-forecasted transaction's date.-  4. Forecasted transactions will end 6 months from today, by default.-     See below for the exact start/end rules.-  5. period expressions can be tricky.  Their documentation needs-     improvement, but is worth studying.-  6. Some period expressions with a repeating interval must begin on a-     natural boundary of that interval.  Eg in 'weekly from DATE', DATE-     must be a monday.  '~ weekly from 2019/10/1' (a tuesday) will give-     an error.-  7. Other period expressions with an interval are automatically-     expanded to cover a whole number of that interval.  (This is done-     to improve reports, but it also affects periodic transactions.-     Yes, it's a bit inconsistent with the above.)  Eg: '~ every 10th-     day of month from 2020/01', which is equivalent to '~ every 10th-     day of month from 2020/01/01', will be adjusted to start on-     2019/12/10.--   Periodic transaction rules also have a second meaning: they are used-to define budget goals, shown in budget reports.--* Menu:--* Periodic rule syntax::-* Two spaces between period expression and description!::-* Forecasting with periodic transactions::-* Budgeting with periodic transactions::---File: hledger.info,  Node: Periodic rule syntax,  Next: Two spaces between period expression and description!,  Up: Periodic transactions--12.28.1 Periodic rule syntax-------------------------------A periodic transaction rule looks like a normal journal entry, with the-date replaced by a tilde ('~') followed by a period expression-(mnemonic: '~' looks like a recurring sine wave.):--~ monthly-    expenses:rent          $2000-    assets:bank:checking--   There is an additional constraint on the period expression: the start-date must fall on a natural boundary of the interval.  Eg 'monthly from-2018/1/1' is valid, but 'monthly from 2018/1/15' is not.--   Partial or relative dates (M/D, D, tomorrow, last week) in the period-expression can work (useful or not).  They will be relative to today's-date, unless a Y default year directive is in effect, in which case they-will be relative to Y/1/1.---File: hledger.info,  Node: Two spaces between period expression and description!,  Next: Forecasting with periodic transactions,  Prev: Periodic rule syntax,  Up: Periodic transactions--12.28.2 Two spaces between period expression and description!----------------------------------------------------------------If the period expression is followed by a transaction description, these-must be separated by *two or more spaces*.  This helps hledger know-where the period expression ends, so that descriptions can not-accidentally alter their meaning, as in this example:--; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2020"-;               ||-;               vv-~ every 2 months  in 2020, we will review-    assets:bank:checking   $1500-    income:acme inc--   So,--   * Do write two spaces between your period expression and your-     transaction description, if any.-   * Don't accidentally write two spaces in the middle of your period-     expression.---File: hledger.info,  Node: Forecasting with periodic transactions,  Next: Budgeting with periodic transactions,  Prev: Two spaces between period expression and description!,  Up: Periodic transactions--12.28.3 Forecasting with periodic transactions-------------------------------------------------The '--forecast' flag activates any periodic transaction rules in the-journal.  These will generate temporary additional transactions, usually-recurring and in the future, which will appear in all reports.  'hledger-print --forecast' is a good way to see them.--   This can be useful for estimating balances into the future, perhaps-experimenting with different scenarios.--   It could also be useful for scripted data entry: you could describe-recurring transactions, and every so often copy the output of 'print---forecast' into the journal.--   The generated transactions will have an extra tag, like-'generated-transaction:~ PERIODICEXPR', indicating which periodic rule-generated them.  There is also a similar, hidden tag, named-'_generated-transaction:', which you can use to reliably match-transactions generated "just now" (rather than 'print'ed in the past).--   The forecast transactions are generated within a _forecast period_,-which is independent of the report period.  (Forecast period sets the-bounds for generated transactions, report period controls which-transactions are reported.)  The forecast period begins on:--   * the start date provided within '--forecast''s argument, if any-   * otherwise, the later of-        * the report start date, if specified (with '-b'/'-p'/'date:')-        * the day after the latest ordinary transaction in the journal,-          if any--   * otherwise today.--   It ends on:--   * the end date provided within '--forecast''s argument, if any-   * otherwise, the report end date, if specified (with-     '-e'/'-p'/'date:')-   * otherwise 180 days (6 months) from today.--   Note, this means that ordinary transactions will suppress periodic-transactions, by default; the periodic transactions will not start until-after the last ordinary transaction.  This is usually convenient, but-you can get around it in two ways:--   * If you need to record some transactions in the future, make them-     periodic transactions (with a single occurrence, eg: '~-     YYYY-MM-DD') rather than ordinary transactions.  That way they-     won't suppress other periodic transactions.--   * Or give '--forecast' a period expression argument.  A forecast-     period specified this way can overlap ordinary transactions, and-     need not be in the future.  Some things to note:--        * You must use '=' between flag and argument; a space won't-          work.-        * The period expression can specify the forecast period's start-          date, end date, or both.  See also Report start & end date.-        * The period expression should not specify a report interval.-          (Each periodic transaction rule specifies its own interval.)--   Some examples: '--forecast=202001-202004', '--forecast=jan-',-'--forecast=2021'.---File: hledger.info,  Node: Budgeting with periodic transactions,  Prev: Forecasting with periodic transactions,  Up: Periodic transactions--12.28.4 Budgeting with periodic transactions-----------------------------------------------With the '--budget' flag, currently supported by the balance command,-each periodic transaction rule declares recurring budget goals for the-specified accounts.  Eg the first example above declares a goal of-spending $2000 on rent (and also, a goal of depositing $2000 into-checking) every month.  Goals and actual performance can then be-compared in budget reports.--   See also: Budgeting and Forecasting.---File: hledger.info,  Node: Auto postings,  Prev: Periodic transactions,  Up: JOURNAL FORMAT--12.29 Auto postings-===================--"Automated postings" or "auto postings" are extra postings which get-added automatically to transactions which match certain queries, defined-by "auto posting rules", when you use the '--auto' flag.--   An auto posting rule looks a bit like a transaction:--= QUERY-    ACCOUNT  AMOUNT-    ...-    ACCOUNT  [AMOUNT]--   except the first line is an equals sign (mnemonic: '=' suggests-matching), followed by a query (which matches existing postings), and-each "posting" line describes a posting to be generated, and the posting-amounts can be:--   * a normal amount with a commodity symbol, eg '$2'.  This will be-     used as-is.-   * a number, eg '2'.  The commodity symbol (if any) from the matched-     posting will be added to this.-   * a numeric multiplier, eg '*2' (a star followed by a number N). The-     matched posting's amount (and total price, if any) will be-     multiplied by N.-   * a multiplier with a commodity symbol, eg '*$2' (a star, number N,-     and symbol S). The matched posting's amount will be multiplied by-     N, and its commodity symbol will be replaced with S.--   Any query term containing spaces must be enclosed in single or double-quotes, as on the command line.  Eg, note the quotes around the second-query term below:--= expenses:groceries 'expenses:dining out'-    (budget:funds:dining out)                 *-1--   Some examples:--; every time I buy food, schedule a dollar donation-= expenses:food-    (liabilities:charity)   $-1--; when I buy a gift, also deduct that amount from a budget envelope subaccount-= expenses:gifts-    assets:checking:gifts  *-1-    assets:checking         *1--2017/12/1-  expenses:food    $10-  assets:checking--2017/12/14-  expenses:gifts   $20-  assets:checking--$ hledger print --auto-2017-12-01-    expenses:food              $10-    assets:checking-    (liabilities:charity)      $-1--2017-12-14-    expenses:gifts             $20-    assets:checking-    assets:checking:gifts     -$20-    assets:checking            $20--* Menu:--* Auto postings and multiple files::-* Auto postings and dates::-* Auto postings and transaction balancing / inferred amounts / balance assertions::-* Auto posting tags::---File: hledger.info,  Node: Auto postings and multiple files,  Next: Auto postings and dates,  Up: Auto postings--12.29.1 Auto postings and multiple files-------------------------------------------An auto posting rule can affect any transaction in the current file, or-in any parent file or child file.  Note, currently it will not affect-sibling files (when multiple '-f'/'--file' are used - see #1212).---File: hledger.info,  Node: Auto postings and dates,  Next: Auto postings and transaction balancing / inferred amounts / balance assertions,  Prev: Auto postings and multiple files,  Up: Auto postings--12.29.2 Auto postings and dates----------------------------------A posting date (or secondary date) in the matched posting, or (taking-precedence) a posting date in the auto posting rule itself, will also be-used in the generated posting.---File: hledger.info,  Node: Auto postings and transaction balancing / inferred amounts / balance assertions,  Next: Auto posting tags,  Prev: Auto postings and dates,  Up: Auto postings--12.29.3 Auto postings and transaction balancing / inferred amounts /-----------------------------------------------------------------------balance assertions Currently, auto postings are added:--   * after missing amounts are inferred, and transactions are checked-     for balancedness,-   * but before balance assertions are checked.--   Note this means that journal entries must be balanced both before and-after auto postings are added.  This changed in hledger 1.12+; see #893-for background.--   This also means that you cannot have more than one auto-posting with-a missing amount applied to a given transaction, as it will be unable to-infer amounts.---File: hledger.info,  Node: Auto posting tags,  Prev: Auto postings and transaction balancing / inferred amounts / balance assertions,  Up: Auto postings--12.29.4 Auto posting tags----------------------------Automated postings will have some extra tags:--   * 'generated-posting:= QUERY' - shows this was generated by an auto-     posting rule, and the query-   * '_generated-posting:= QUERY' - a hidden tag, which does not appear-     in hledger's output.  This can be used to match postings generated-     "just now", rather than generated in the past and saved to the-     journal.--   Also, any transaction that has been changed by auto posting rules-will have these tags added:--   * 'modified:' - this transaction was modified-   * '_modified:' - a hidden tag not appearing in the comment; this-     transaction was modified "just now".---File: hledger.info,  Node: CSV FORMAT,  Next: TIMECLOCK FORMAT,  Prev: JOURNAL FORMAT,  Up: Top--13 CSV FORMAT-*************--How hledger reads CSV data, and the CSV rules file format.--   hledger can read CSV files (Character Separated Value - usually-comma, semicolon, or tab) containing dated records as if they were-journal files, automatically converting each CSV record into a-transaction.--   (To learn about _writing_ CSV, see CSV output.)--   We describe each CSV file's format with a corresponding _rules file_.-By default this is named like the CSV file with a '.rules' extension-added.  Eg when reading 'FILE.csv', hledger also looks for-'FILE.csv.rules' in the same directory as 'FILE.csv'.  You can specify a-different rules file with the '--rules-file' option.  If a rules file is-not found, hledger will create a sample rules file, which you'll need to-adjust.--   This file contains rules describing the CSV data (header line, fields-layout, date format etc.), and how to construct hledger journal entries-(transactions) from it.  Often there will also be a list of conditional-rules for categorising transactions based on their descriptions.  Here's-an overview of the CSV rules; these are described more fully below,-after the examples:--*'skip'*                    skip one or more header lines or matched-                            CSV records-*'fields' list*             name CSV fields, assign them to hledger-                            fields-*field assignment*          assign a value to one hledger field, with-                            interpolation-*Field names*               hledger field names, used in the fields-                            list and field assignments-*'separator'*               a custom field separator-*'if' block*                apply some rules to CSV records matched by-                            patterns-*'if' table*                apply some rules to CSV records matched by-                            patterns, alternate syntax-*'end'*                     skip the remaining CSV records-*'date-format'*             how to parse dates in CSV records-*'decimal-mark'*            the decimal mark used in CSV amounts, if-                            ambiguous-*'newest-first'*            disambiguate record order when there's only-                            one date-*'include'*                 inline another CSV rules file-*'balance-type'*            choose which type of balance assignments to-                            use--   Note, for best error messages when reading CSV files, use a '.csv',-'.tsv' or '.ssv' file extension or file prefix - see File Extension-below.--   There's an introductory Convert CSV files tutorial on hledger.org.--* Menu:--* Examples::-* CSV rules::-* Tips::---File: hledger.info,  Node: Examples,  Next: CSV rules,  Up: CSV FORMAT--13.1 Examples-=============--Here are some sample hledger CSV rules files.  See also the full-collection at:-https://github.com/simonmichael/hledger/tree/master/examples/csv--* Menu:--* Basic::-* Bank of Ireland::-* Amazon::-* Paypal::---File: hledger.info,  Node: Basic,  Next: Bank of Ireland,  Up: Examples--13.1.1 Basic---------------At minimum, the rules file must identify the date and amount fields, and-often it also specifies the date format and how many header lines there-are.  Here's a simple CSV file and a rules file for it:--Date, Description, Id, Amount-12/11/2019, Foo, 123, 10.23--# basic.csv.rules-skip         1-fields       date, description, _, amount-date-format  %d/%m/%Y--$ hledger print -f basic.csv-2019-11-12 Foo-    expenses:unknown           10.23-    income:unknown            -10.23--   Default account names are chosen, since we didn't set them.---File: hledger.info,  Node: Bank of Ireland,  Next: Amazon,  Prev: Basic,  Up: Examples--13.1.2 Bank of Ireland-------------------------Here's a CSV with two amount fields (Debit and Credit), and a balance-field, which we can use to add balance assertions, which is not-necessary but provides extra error checking:--Date,Details,Debit,Credit,Balance-07/12/2012,LODGMENT       529898,,10.0,131.21-07/12/2012,PAYMENT,5,,126--# bankofireland-checking.csv.rules--# skip the header line-skip--# name the csv fields, and assign some of them as journal entry fields-fields  date, description, amount-out, amount-in, balance--# We generate balance assertions by assigning to "balance"-# above, but you may sometimes need to remove these because:-#-# - the CSV balance differs from the true balance,-#   by up to 0.0000000000005 in my experience-#-# - it is sometimes calculated based on non-chronological ordering,-#   eg when multiple transactions clear on the same day--# date is in UK/Ireland format-date-format  %d/%m/%Y--# set the currency-currency  EUR--# set the base account for all txns-account1  assets:bank:boi:checking--$ hledger -f bankofireland-checking.csv print-2012-12-07 LODGMENT       529898-    assets:bank:boi:checking         EUR10.0 = EUR131.2-    income:unknown                  EUR-10.0--2012-12-07 PAYMENT-    assets:bank:boi:checking         EUR-5.0 = EUR126.0-    expenses:unknown                  EUR5.0--   The balance assertions don't raise an error above, because we're-reading directly from CSV, but they will be checked if these entries are-imported into a journal file.---File: hledger.info,  Node: Amazon,  Next: Paypal,  Prev: Bank of Ireland,  Up: Examples--13.1.3 Amazon----------------Here we convert amazon.com order history, and use an if block to-generate a third posting if there's a fee.  (In practice you'd probably-get this data from your bank instead, but it's an example.)--"Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID"-"Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL"-"Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL"--# amazon-orders.csv.rules--# skip one header line-skip 1--# name the csv fields, and assign the transaction's date, amount and code.-# Avoided the "status" and "amount" hledger field names to prevent confusion.-fields date, _, toorfrom, name, amzstatus, amzamount, fees, code--# how to parse the date-date-format %b %-d, %Y--# combine two fields to make the description-description %toorfrom %name--# save the status as a tag-comment     status:%amzstatus--# set the base account for all transactions-account1    assets:amazon-# leave amount1 blank so it can balance the other(s).-# I'm assuming amzamount excludes the fees, don't remember--# set a generic account2-account2    expenses:misc-amount2     %amzamount-# and maybe refine it further:-#include categorisation.rules--# add a third posting for fees, but only if they are non-zero.-if %fees [1-9]- account3    expenses:fees- amount3     %fees--$ hledger -f amazon-orders.csv print-2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo.  ; status:Completed-    assets:amazon-    expenses:misc          $20.00--2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc.  ; status:Completed-    assets:amazon-    expenses:misc          $25.00-    expenses:fees           $1.00---File: hledger.info,  Node: Paypal,  Prev: Amazon,  Up: Examples--13.1.4 Paypal----------------Here's a real-world rules file for (customised) Paypal CSV, with some-Paypal-specific rules, and a second rules file included:--"Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"-"10/01/2019","03:46:20","PDT","Calm Radio","Subscription Payment","Completed","USD","-6.99","0.00","-6.99","simon@joyful.com","memberships@calmradio.com","60P57143A8206782E","MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month","","I-R8YLY094FJYR","","-6.99",""-"10/01/2019","03:46:20","PDT","","Bank Deposit to PP Account ","Pending","USD","6.99","0.00","6.99","","simon@joyful.com","0TU1544T080463733","","","60P57143A8206782E","","0.00",""-"10/01/2019","08:57:01","PDT","Patreon","PreApproved Payment Bill User Payment","Completed","USD","-7.00","0.00","-7.00","simon@joyful.com","support@patreon.com","2722394R5F586712G","Patreon* Membership","","B-0PG93074E7M86381M","","-7.00",""-"10/01/2019","08:57:01","PDT","","Bank Deposit to PP Account ","Pending","USD","7.00","0.00","7.00","","simon@joyful.com","71854087RG994194F","Patreon* Membership","","2722394R5F586712G","","0.00",""-"10/19/2019","03:02:12","PDT","Wikimedia Foundation, Inc.","Subscription Payment","Completed","USD","-2.00","0.00","-2.00","simon@joyful.com","tle@wikimedia.org","K9U43044RY432050M","Monthly donation to the Wikimedia Foundation","","I-R5C3YUS3285L","","-2.00",""-"10/19/2019","03:02:12","PDT","","Bank Deposit to PP Account ","Pending","USD","2.00","0.00","2.00","","simon@joyful.com","3XJ107139A851061F","","","K9U43044RY432050M","","0.00",""-"10/22/2019","05:07:06","PDT","Noble Benefactor","Subscription Payment","Completed","USD","10.00","-0.59","9.41","noble@bene.fac.tor","simon@joyful.com","6L8L1662YP1334033","Joyful Systems","","I-KC9VBGY2GWDB","","9.41",""--# paypal-custom.csv.rules--# Tips:-# Export from Activity -> Statements -> Custom -> Activity download-# Suggested transaction type: "Balance affecting"-# Paypal's default fields in 2018 were:-# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Shipping Address","Address Status","Item Title","Item ID","Shipping and Handling Amount","Insurance Amount","Sales Tax","Option 1 Name","Option 1 Value","Option 2 Name","Option 2 Value","Reference Txn ID","Invoice Number","Custom Number","Quantity","Receipt ID","Balance","Address Line 1","Address Line 2/District/Neighborhood","Town/City","State/Province/Region/County/Territory/Prefecture/Republic","Zip/Postal Code","Country","Contact Phone Number","Subject","Note","Country Code","Balance Impact"-# This rules file assumes the following more detailed fields, configured in "Customize report fields":-# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"--fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note--skip  1--date-format  %-m/%-d/%Y--# ignore some paypal events-if-In Progress-Temporary Hold-Update to- skip--# add more fields to the description-description %description_ %itemtitle--# save some other fields as tags-comment  itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_--# convert to short currency symbols-if %currency USD- currency $-if %currency EUR- currency E-if %currency GBP- currency P--# generate postings--# the first posting will be the money leaving/entering my paypal account-# (negative means leaving my account, in all amount fields)-account1 assets:online:paypal-amount1  %netamount--# the second posting will be money sent to/received from other party-# (account2 is set below)-amount2  -%grossamount--# if there's a fee, add a third posting for the money taken by paypal.-if %feeamount [1-9]- account3 expenses:banking:paypal- amount3  -%feeamount- comment3 business:--# choose an account for the second posting--# override the default account names:-# if the amount is positive, it's income (a debit)-if %grossamount ^[^-]- account2 income:unknown-# if negative, it's an expense (a credit)-if %grossamount ^-- account2 expenses:unknown--# apply common rules for setting account2 & other tweaks-include common.rules--# apply some overrides specific to this csv--# Transfers from/to bank. These are usually marked Pending,-# which can be disregarded in this case.-if-Bank Account-Bank Deposit to PP Account- description %type for %referencetxnid %itemtitle- account2 assets:bank:wf:pchecking- account1 assets:online:paypal--# Currency conversions-if Currency Conversion- account2 equity:currency conversion--# common.rules--if-darcs-noble benefactor- account2 revenues:foss donations:darcshub- comment2 business:--if-Calm Radio- account2 expenses:online:apps--if-electronic frontier foundation-Patreon-wikimedia-Advent of Code- account2 expenses:dues--if Google- account2 expenses:online:apps- description google | music--$ hledger -f paypal-custom.csv  print-2019-10-01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month  ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed-    assets:online:paypal          $-6.99 = $-6.99-    expenses:online:apps           $6.99--2019-10-01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E  ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending-    assets:online:paypal               $6.99 = $0.00-    assets:bank:wf:pchecking          $-6.99--2019-10-01 (2722394R5F586712G) Patreon Patreon* Membership  ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed-    assets:online:paypal          $-7.00 = $-7.00-    expenses:dues                  $7.00--2019-10-01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership  ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending-    assets:online:paypal               $7.00 = $0.00-    assets:bank:wf:pchecking          $-7.00--2019-10-19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation  ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed-    assets:online:paypal             $-2.00 = $-2.00-    expenses:dues                     $2.00-    expenses:banking:paypal      ; business:--2019-10-19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M  ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending-    assets:online:paypal               $2.00 = $0.00-    assets:bank:wf:pchecking          $-2.00--2019-10-22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems  ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed-    assets:online:paypal                       $9.41 = $9.41-    revenues:foss donations:darcshub         $-10.00  ; business:-    expenses:banking:paypal                    $0.59  ; business:---File: hledger.info,  Node: CSV rules,  Next: Tips,  Prev: Examples,  Up: CSV FORMAT--13.2 CSV rules-==============--The following kinds of rule can appear in the rules file, in any order.-Blank lines and lines beginning with '#' or ';' are ignored.--* Menu:--* skip::-* fields list::-* field assignment::-* Field names::-* separator::-* if block::-* if table::-* end::-* date-format::-* decimal-mark::-* newest-first::-* include::-* balance-type::---File: hledger.info,  Node: skip,  Next: fields list,  Up: CSV rules--13.2.1 'skip'----------------skip N--   The word "skip" followed by a number (or no number, meaning 1) tells-hledger to ignore this many non-empty lines preceding the CSV data.-(Empty/blank lines are skipped automatically.)  You'll need this-whenever your CSV data contains header lines.--   It also has a second purpose: it can be used inside if blocks to-ignore certain CSV records (described below).---File: hledger.info,  Node: fields list,  Next: field assignment,  Prev: skip,  Up: CSV rules--13.2.2 'fields' list-----------------------fields FIELDNAME1, FIELDNAME2, ...--   A fields list (the word "fields" followed by comma-separated field-names) is the quick way to assign CSV field values to hledger fields.-(The other way is field assignments, see below.)  A fields list does-does two things:--  1. It names the CSV fields.  This is optional, but can be convenient-     later for interpolating them.--  2. Whenever you use a standard hledger field name (defined below), the-     CSV value is assigned to that part of the hledger transaction.--   Here's an example that says "use the 1st, 2nd and 4th fields as the-transaction's date, description and amount; name the last two fields for-later reference; and ignore the others":--fields date, description, , amount, , , somefield, anotherfield--   Tips:--   * The fields list always use commas, even if your CSV data uses-     another separator character.-   * Currently there must be least two items in the list (at least one-     comma).-   * Field names may not contain spaces.  Spaces before/after field-     names are optional.-   * Field names may contain '_' (underscore) or '-' (hyphen).-   * If the CSV contains column headings, it's a good idea to use these,-     suitably modified, as the basis for your field names (eg-     lower-cased, with underscores instead of spaces).-   * If some heading names match standard hledger fields, but you don't-     want to set the hledger fields directly, alter those names, eg by-     appending an underscore.-   * Fields you don't care about can be given a dummy name (eg: '_' ),-     or no name.---File: hledger.info,  Node: field assignment,  Next: Field names,  Prev: fields list,  Up: CSV rules--13.2.3 field assignment--------------------------HLEDGERFIELDNAME FIELDVALUE--   Field assignments are the more flexible way to assign CSV values to-hledger fields.  They can be used instead of or in addition to a fields-list (see above).--   To assign a value to a hledger field, write the field name (any of-the standard hledger field/pseudo-field names, defined below), a space,-followed by a text value on the same line.  This text value may-interpolate CSV fields, referenced by their 1-based position in the CSV-record ('%N'), or by the name they were given in the fields list-('%CSVFIELDNAME').--   Some examples:--# set the amount to the 4th CSV field, with " USD" appended-amount %4 USD--# combine three fields to make a comment, containing note: and date: tags-comment note: %somefield - %anotherfield, date: %1--   Tips:--   * Interpolation strips outer whitespace (so a CSV value like '" 1 "'-     becomes '1' when interpolated) (#1051).-   * Interpolations always refer to a CSV field - you can't interpolate-     a hledger field.  (See Referencing other fields below).---File: hledger.info,  Node: Field names,  Next: separator,  Prev: field assignment,  Up: CSV rules--13.2.4 Field names---------------------Here are the standard hledger field (and pseudo-field) names, which you-can use in a fields list and in field assignments.  For more about the-transaction parts they refer to, see Transactions.--* Menu:--* date field::-* date2 field::-* status field::-* code field::-* description field::-* comment field::-* account field::-* amount field::-* currency field::-* balance field::---File: hledger.info,  Node: date field,  Next: date2 field,  Up: Field names--13.2.4.1 date field-...................--Assigning to 'date' sets the transaction date.---File: hledger.info,  Node: date2 field,  Next: status field,  Prev: date field,  Up: Field names--13.2.4.2 date2 field-....................--'date2' sets the transaction's secondary date, if any.---File: hledger.info,  Node: status field,  Next: code field,  Prev: date2 field,  Up: Field names--13.2.4.3 status field-.....................--'status' sets the transaction's status, if any.---File: hledger.info,  Node: code field,  Next: description field,  Prev: status field,  Up: Field names--13.2.4.4 code field-...................--'code' sets the transaction's code, if any.---File: hledger.info,  Node: description field,  Next: comment field,  Prev: code field,  Up: Field names--13.2.4.5 description field-..........................--'description' sets the transaction's description, if any.---File: hledger.info,  Node: comment field,  Next: account field,  Prev: description field,  Up: Field names--13.2.4.6 comment field-......................--'comment' sets the transaction's comment, if any.--   'commentN', where N is a number, sets the Nth posting's comment.--   Tips:--   * You can assign multi-line comments by writing literal '\n' in the-     code.  A comment starting with '\n' will begin on a new line.-   * Comments can contain tags, as usual.---File: hledger.info,  Node: account field,  Next: amount field,  Prev: comment field,  Up: Field names--13.2.4.7 account field-......................--Assigning to 'accountN', where N is 1 to 99, sets the account name of-the Nth posting, and causes that posting to be generated.--   Most often there are two postings, so you'll want to set 'account1'-and 'account2'.  Typically 'account1' is associated with the CSV file,-and is set once with a top-level assignment, while 'account2' is set-based on each transaction's description, and in conditional blocks.--   If a posting's account name is left unset but its amount is set (see-below), a default account name will be chosen (like "expenses:unknown"-or "income:unknown").---File: hledger.info,  Node: amount field,  Next: currency field,  Prev: account field,  Up: Field names--13.2.4.8 amount field-.....................--'amountN' sets the amount of the Nth posting, and causes that posting to-be generated.  By assigning to 'amount1', 'amount2', ...  etc.  you can-generate up to 99 postings.--   'amountN-in' and 'amountN-out' can be used instead, if the CSV uses-separate fields for debits and credits (inflows and outflows).  hledger-assumes both of these CSV fields are unsigned, and will automatically-negate the "-out" value.  If they are signed, see "Setting amounts"-below.--   'amount', or 'amount-in' and 'amount-out' are a legacy mode, to keep-pre-hledger-1.17 CSV rules files working (and for occasional-convenience).  They are suitable only for two-posting transactions; they-set both posting 1's and posting 2's amount.  Posting 2's amount will be-negated, and also converted to cost if there's a transaction price.--   If you have an existing rules file using the unnumbered form, you-might want to use the numbered form in certain conditional blocks,-without having to update and retest all the old rules.  To facilitate-this, posting 1 ignores 'amount'/'amount-in'/'amount-out' if any of-'amount1'/'amount1-in'/'amount1-out' are assigned, and posting 2 ignores-them if any of 'amount2'/'amount2-in'/'amount2-out' are assigned,-avoiding conflicts.---File: hledger.info,  Node: currency field,  Next: balance field,  Prev: amount field,  Up: Field names--13.2.4.9 currency field-.......................--'currency' sets a currency symbol, to be prepended to all postings'-amounts.  You can use this if the CSV amounts do not have a currency-symbol, eg if it is in a separate column.--   'currencyN' prepends a currency symbol to just the Nth posting's-amount.---File: hledger.info,  Node: balance field,  Prev: currency field,  Up: Field names--13.2.4.10 balance field-.......................--'balanceN' sets a balance assertion amount (or if the posting amount is-left empty, a balance assignment) on posting N.--   'balance' is a compatibility spelling for hledger <1.17; it is-equivalent to 'balance1'.--   You can adjust the type of assertion/assignment with the-'balance-type' rule (see below).--   See Tips below for more about setting amounts and currency.---File: hledger.info,  Node: separator,  Next: if block,  Prev: Field names,  Up: CSV rules--13.2.5 'separator'---------------------You can use the 'separator' rule to read other kinds of-character-separated data.  The argument is any single separator-character, or the words 'tab' or 'space' (case insensitive).  Eg, for-comma-separated values (CSV):--separator ,--   or for semicolon-separated values (SSV):--separator ;--   or for tab-separated values (TSV):--separator TAB--   If the input file has a '.csv', '.ssv' or '.tsv' file extension (or a-'csv:', 'ssv:', 'tsv:' prefix), the appropriate separator will be-inferred automatically, and you won't need this rule.---File: hledger.info,  Node: if block,  Next: if table,  Prev: separator,  Up: CSV rules--13.2.6 'if' block--------------------if MATCHER- RULE--if-MATCHER-MATCHER-MATCHER- RULE- RULE--   Conditional blocks ("if blocks") are a block of rules that are-applied only to CSV records which match certain patterns.  They are-often used for customising account names based on transaction-descriptions.--* Menu:--* Matching the whole record::-* Matching individual fields::-* Combining matchers::-* Rules applied on successful match::---File: hledger.info,  Node: Matching the whole record,  Next: Matching individual fields,  Up: if block--13.2.6.1 Matching the whole record-..................................--Each MATCHER can be a record matcher, which looks like this:--REGEX--   REGEX is a case-insensitive regular expression that tries to match-anywhere within the CSV record.  It is a POSIX ERE (extended regular-expression) that also supports GNU word boundaries ('\b', '\B', '\<',-'\>'), and nothing else.  If you have trouble, be sure to check our doc:-https://hledger.org/hledger.html#regular-expressions--   Important note: the record that is matched is not the original-record, but a synthetic one, with any enclosing double quotes (but not-enclosing whitespace) removed, and always comma-separated (which means-that a field containing a comma will appear like two fields).  Eg, if-the original record is '2020-01-01; "Acme, Inc."; 1,000', the REGEX will-actually see '2020-01-01,Acme, Inc., 1,000').---File: hledger.info,  Node: Matching individual fields,  Next: Combining matchers,  Prev: Matching the whole record,  Up: if block--13.2.6.2 Matching individual fields-...................................--Or, MATCHER can be a field matcher, like this:--%CSVFIELD REGEX--   which matches just the content of a particular CSV field.  CSVFIELD-is a percent sign followed by the field's name or column number, like-'%date' or '%1'.---File: hledger.info,  Node: Combining matchers,  Next: Rules applied on successful match,  Prev: Matching individual fields,  Up: if block--13.2.6.3 Combining matchers-...........................--A single matcher can be written on the same line as the "if"; or-multiple matchers can be written on the following lines, non-indented.-Multiple matchers are OR'd (any one of them can match), unless one-begins with an '&' symbol, in which case it is AND'ed with the previous-matcher.--if-MATCHER-& MATCHER- RULE---File: hledger.info,  Node: Rules applied on successful match,  Prev: Combining matchers,  Up: if block--13.2.6.4 Rules applied on successful match-..........................................--After the patterns there should be one or more rules to apply, all-indented by at least one space.  Three kinds of rule are allowed in-conditional blocks:--   * field assignments (to set a hledger field)-   * skip (to skip the matched CSV record)-   * end (to skip all remaining CSV records).--   Examples:--# if the CSV record contains "groceries", set account2 to "expenses:groceries"-if groceries- account2 expenses:groceries--# if the CSV record contains any of these patterns, set account2 and comment as shown-if-monthly service fee-atm transaction fee-banking thru software- account2 expenses:business:banking- comment  XXX deductible ? check it---File: hledger.info,  Node: if table,  Next: end,  Prev: if block,  Up: CSV rules--13.2.7 'if' table--------------------if,CSVFIELDNAME1,CSVFIELDNAME2,...,CSVFIELDNAMEn-MATCHER1,VALUE11,VALUE12,...,VALUE1n-MATCHER2,VALUE21,VALUE22,...,VALUE2n-MATCHER3,VALUE31,VALUE32,...,VALUE3n-<empty line>--   Conditional tables ("if tables") are a different syntax to specify-field assignments that will be applied only to CSV records which match-certain patterns.--   MATCHER could be either field or record matcher, as described above.-When MATCHER matches, values from that row would be assigned to the CSV-fields named on the 'if' line, in the same order.--   Therefore 'if' table is exactly equivalent to a sequence of of 'if'-blocks:--if MATCHER1-  CSVFIELDNAME1 VALUE11-  CSVFIELDNAME2 VALUE12-  ...-  CSVFIELDNAMEn VALUE1n--if MATCHER2-  CSVFIELDNAME1 VALUE21-  CSVFIELDNAME2 VALUE22-  ...-  CSVFIELDNAMEn VALUE2n--if MATCHER3-  CSVFIELDNAME1 VALUE31-  CSVFIELDNAME2 VALUE32-  ...-  CSVFIELDNAMEn VALUE3n--   Each line starting with MATCHER should contain enough (possibly-empty) values for all the listed fields.--   Rules would be checked and applied in the order they are listed in-the table and, like with 'if' blocks, later rules (in the same or-another table) or 'if' blocks could override the effect of any rule.--   Instead of ',' you can use a variety of other non-alphanumeric-characters as a separator.  First character after 'if' is taken to be-the separator for the rest of the table.  It is the responsibility of-the user to ensure that separator does not occur inside MATCHERs and-values - there is no way to escape separator.--   Example:--if,account2,comment-atm transaction fee,expenses:business:banking,deductible? check it-%description groceries,expenses:groceries,-2020/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out---File: hledger.info,  Node: end,  Next: date-format,  Prev: if table,  Up: CSV rules--13.2.8 'end'---------------This rule can be used inside if blocks (only), to make hledger stop-reading this CSV file and move on to the next input file, or to command-execution.  Eg:--# ignore everything following the first empty record-if ,,,,- end---File: hledger.info,  Node: date-format,  Next: decimal-mark,  Prev: end,  Up: CSV rules--13.2.9 'date-format'-----------------------date-format DATEFMT--   This is a helper for the 'date' (and 'date2') fields.  If your CSV-dates are not formatted like 'YYYY-MM-DD', 'YYYY/MM/DD' or 'YYYY.MM.DD',-you'll need to add a date-format rule describing them with a strptime-date parsing pattern, which must parse the CSV date value completely.-Some examples:--# MM/DD/YY-date-format %m/%d/%y--# D/M/YYYY-# The - makes leading zeros optional.-date-format %-d/%-m/%Y--# YYYY-Mmm-DD-date-format %Y-%h-%d--# M/D/YYYY HH:MM AM some other junk-# Note the time and junk must be fully parsed, though only the date is used.-date-format %-m/%-d/%Y %l:%M %p some other junk--   For the supported strptime syntax, see:-https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime--   Note that although you can parse date-times which include a time-zone, that time zone is ignored; it will not change the date that is-parsed.  This means when reading CSV data with times not in your local-time zone, dates can be "off by one".---File: hledger.info,  Node: decimal-mark,  Next: newest-first,  Prev: date-format,  Up: CSV rules--13.2.10 'decimal-mark'-------------------------decimal-mark .--   or:--decimal-mark ,--   hledger automatically accepts either period or comma as a decimal-mark when parsing numbers (cf Amounts).  However if any numbers in the-CSV contain digit group marks, such as thousand-separating commas, you-should declare the decimal mark explicitly with this rule, to avoid-misparsed numbers.---File: hledger.info,  Node: newest-first,  Next: include,  Prev: decimal-mark,  Up: CSV rules--13.2.11 'newest-first'-------------------------hledger always sorts the generated transactions by date.  Transactions-on the same date should appear in the same order as their CSV records,-as hledger can usually auto-detect whether the CSV's normal order is-oldest first or newest first.  But if all of the following are true:--   * the CSV might sometimes contain just one day of data (all records-     having the same date)-   * the CSV records are normally in reverse chronological order (newest-     at the top)-   * and you care about preserving the order of same-day transactions--   then, you should add the 'newest-first' rule as a hint.  Eg:--# tell hledger explicitly that the CSV is normally newest first-newest-first---File: hledger.info,  Node: include,  Next: balance-type,  Prev: newest-first,  Up: CSV rules--13.2.12 'include'--------------------include RULESFILE--   This includes the contents of another CSV rules file at this point.-'RULESFILE' is an absolute file path or a path relative to the current-file's directory.  This can be useful for sharing common rules between-several rules files, eg:--# someaccount.csv.rules--## someaccount-specific rules-fields   date,description,amount-account1 assets:someaccount-account2 expenses:misc--## common rules-include categorisation.rules---File: hledger.info,  Node: balance-type,  Prev: include,  Up: CSV rules--13.2.13 'balance-type'-------------------------Balance assertions generated by assigning to balanceN are of the simple-'=' type by default, which is a single-commodity, subaccount-excluding-assertion.  You may find the subaccount-including variants more useful,-eg if you have created some virtual subaccounts of checking to help with-budgeting.  You can select a different type of assertion with the-'balance-type' rule:--# balance assertions will consider all commodities and all subaccounts-balance-type ==*--   Here are the balance assertion types for quick reference:--=    single commodity, exclude subaccounts-=*   single commodity, include subaccounts-==   multi commodity,  exclude subaccounts-==*  multi commodity,  include subaccounts---File: hledger.info,  Node: Tips,  Prev: CSV rules,  Up: CSV FORMAT--13.3 Tips-=========--* Menu:--* Rapid feedback::-* Valid CSV::-* File Extension::-* Reading multiple CSV files::-* Valid transactions::-* Deduplicating importing::-* Setting amounts::-* Amount signs::-* Setting currency/commodity::-* Amount decimal places::-* Referencing other fields::-* How CSV rules are evaluated::---File: hledger.info,  Node: Rapid feedback,  Next: Valid CSV,  Up: Tips--13.3.1 Rapid feedback------------------------It's a good idea to get rapid feedback while creating/troubleshooting-CSV rules.  Here's a good way, using entr from eradman.com/entrproject:--$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC'--   A desc: query (eg) is used to select just one, or a few, transactions-of interest.  "bash -c" is used to run multiple commands, so we can echo-a separator each time the command re-runs, making it easier to read the-output.---File: hledger.info,  Node: Valid CSV,  Next: File Extension,  Prev: Rapid feedback,  Up: Tips--13.3.2 Valid CSV-------------------hledger accepts CSV conforming to RFC 4180.  When CSV values are-enclosed in quotes, note:--   * they must be double quotes (not single quotes)-   * spaces outside the quotes are not allowed---File: hledger.info,  Node: File Extension,  Next: Reading multiple CSV files,  Prev: Valid CSV,  Up: Tips--13.3.3 File Extension------------------------To help hledger identify the format and show the right error messages,-CSV/SSV/TSV files should normally be named with a '.csv', '.ssv' or-'.tsv' filename extension.  Or, the file path should be prefixed with-'csv:', 'ssv:' or 'tsv:'.  Eg:--$ hledger -f foo.ssv print--   or:--$ cat foo | hledger -f ssv:- foo--   You can override the file extension with a separator rule if needed.-See also: Input files in the hledger manual.---File: hledger.info,  Node: Reading multiple CSV files,  Next: Valid transactions,  Prev: File Extension,  Up: Tips--13.3.4 Reading multiple CSV files------------------------------------If you use multiple '-f' options to read multiple CSV files at once,-hledger will look for a correspondingly-named rules file for each CSV-file.  But if you use the '--rules-file' option, that rules file will be-used for all the CSV files.---File: hledger.info,  Node: Valid transactions,  Next: Deduplicating importing,  Prev: Reading multiple CSV files,  Up: Tips--13.3.5 Valid transactions----------------------------After reading a CSV file, hledger post-processes and validates the-generated journal entries as it would for a journal file - balancing-them, applying balance assignments, and canonicalising amount styles.-Any errors at this stage will be reported in the usual way, displaying-the problem entry.--   There is one exception: balance assertions, if you have generated-them, will not be checked, since normally these will work only when the-CSV data is part of the main journal.  If you do need to check balance-assertions generated from CSV right away, pipe into another hledger:--$ hledger -f file.csv print | hledger -f- print---File: hledger.info,  Node: Deduplicating importing,  Next: Setting amounts,  Prev: Valid transactions,  Up: Tips--13.3.6 Deduplicating, importing----------------------------------When you download a CSV file periodically, eg to get your latest bank-transactions, the new file may overlap with the old one, containing some-of the same records.--   The import command will (a) detect the new transactions, and (b)-append just those transactions to your main journal.  It is idempotent,-so you don't have to remember how many times you ran it or with which-version of the CSV. (It keeps state in a hidden '.latest.FILE.csv'-file.)  This is the easiest way to import CSV data.  Eg:--# download the latest CSV files, then run this command.-# Note, no -f flags needed here.-$ hledger import *.csv [--dry]--   This method works for most CSV files.  (Where records have a stable-chronological order, and new records appear only at the new end.)--   A number of other tools and workflows, hledger-specific and-otherwise, exist for converting, deduplicating, classifying and managing-CSV data.  See:--   * https://hledger.org -> sidebar -> real world setups-   * https://plaintextaccounting.org -> data import/conversion---File: hledger.info,  Node: Setting amounts,  Next: Amount signs,  Prev: Deduplicating importing,  Up: Tips--13.3.7 Setting amounts-------------------------Some tips on using the amount-setting rules discussed above.--   Here are the ways to set a posting's amount:--  1. *If the CSV has a single amount field:*-     Assign (via a fields list or a field assignment) to 'amountN'.-     This sets the Nth posting's amount.  N is usually 1 or 2 but can go-     up to 99.--  2. *If the CSV has separate amount fields for debit & credit (in &-     out):*--       a. *If both fields are unsigned:*-          Assign to 'amountN-in' and 'amountN-out'.  This sets posting-          N's amount to whichever of these has a non-zero value, and-          negates the "-out" value.--       b. *If either field is signed (can contain a minus sign):*-          Use a conditional rule to flip the sign (of non-empty values).-          Since hledger always negates amountN-out, if it was already-          negative, we must undo that by negating once more (but only if-          the field is non-empty):--     fields date, description, amount1-in, amount1-out-     if %amount1-out [1-9]-      amount1-out -%amount1-out--       c. *If both fields, or neither field, can contain a non-zero-          value:*-          hledger normally expects exactly one of the fields to have a-          non-zero value.  Eg, the 'amountN-in'/'amountN-out' rules-          would reject value pairs like these:--     "",  ""-     "0", "0"-     "1", "none"--     So, use smarter conditional rules to set the amount from the-     appropriate field.  Eg, these rules would make it use only the-     value containing non-zero digits, handling the above:--     fields date, description, in, out-     if %in [1-9]-      amount1 %in-     if %out [1-9]-      amount1 %out--  3. *If you are stuck with hledger <1.17, or you want posting 2's-     amount converted to cost:*-     Assign to 'amount' (or to 'amount-in' and 'amount-out').  (The old-     numberless syntax, which sets amount1 and amount2.)--  4. *If the CSV has the balance instead of the transaction amount:*-     Assign to 'balanceN', which sets posting N's amount indirectly via-     a balance assignment.  (Old syntax: 'balance', equivalent to-     'balance1'.)--        * *If hledger guesses the wrong default account name:*-          When setting the amount via balance assertion, hledger may-          guess the wrong default account name.  So, set the account-          name explicitly, eg:--          fields date, description, balance1-          account1 assets:checking---File: hledger.info,  Node: Amount signs,  Next: Setting currency/commodity,  Prev: Setting amounts,  Up: Tips--13.3.8 Amount signs----------------------There is some special handling for amount signs, to simplify parsing and-sign-flipping:--   * *If an amount value begins with a plus sign:*-     that will be removed: '+AMT' becomes 'AMT'--   * *If an amount value is parenthesised:*-     it will be de-parenthesised and sign-flipped: '(AMT)' becomes-     '-AMT'--   * *If an amount value has two minus signs (or two sets of-     parentheses, or a minus sign and parentheses):*-     they cancel out and will be removed: '--AMT' or '-(AMT)' becomes-     'AMT'--   * *If an amount value contains just a sign (or just a set of-     parentheses):*-     that is removed, making it an empty value.  '"+"' or '"-"' or-     '"()"' becomes '""'.---File: hledger.info,  Node: Setting currency/commodity,  Next: Amount decimal places,  Prev: Amount signs,  Up: Tips--13.3.9 Setting currency/commodity------------------------------------If the currency/commodity symbol is included in the CSV's amount-field(s):--2020-01-01,foo,$123.00--   you don't have to do anything special for the commodity symbol, it-will be assigned as part of the amount.  Eg:--fields date,description,amount--2020-01-01 foo-    expenses:unknown         $123.00-    income:unknown          $-123.00--   If the currency is provided as a separate CSV field:--2020-01-01,foo,USD,123.00--   You can assign that to the 'currency' pseudo-field, which has the-special effect of prepending itself to every amount in the transaction-(on the left, with no separating space):--fields date,description,currency,amount--2020-01-01 foo-    expenses:unknown       USD123.00-    income:unknown        USD-123.00--   Or, you can use a field assignment to construct the amount yourself,-with more control.  Eg to put the symbol on the right, and separated by-a space:--fields date,description,cur,amt-amount %amt %cur--2020-01-01 foo-    expenses:unknown        123.00 USD-    income:unknown         -123.00 USD--   Note we used a temporary field name ('cur') that is not 'currency' --that would trigger the prepending effect, which we don't want here.---File: hledger.info,  Node: Amount decimal places,  Next: Referencing other fields,  Prev: Setting currency/commodity,  Up: Tips--13.3.10 Amount decimal places--------------------------------Like amounts in a journal file, the amounts generated by CSV rules like-'amount1' influence commodity display styles, such as the number of-decimal places displayed in reports.--   The original amounts as written in the CSV file do not affect display-style (because we don't yet reliably know their commodity).---File: hledger.info,  Node: Referencing other fields,  Next: How CSV rules are evaluated,  Prev: Amount decimal places,  Up: Tips--13.3.11 Referencing other fields-----------------------------------In field assignments, you can interpolate only CSV fields, not hledger-fields.  In the example below, there's both a CSV field and a hledger-field named amount1, but %amount1 always means the CSV field, not the-hledger field:--# Name the third CSV field "amount1"-fields date,description,amount1--# Set hledger's amount1 to the CSV amount1 field followed by USD-amount1 %amount1 USD--# Set comment to the CSV amount1 (not the amount1 assigned above)-comment %amount1--   Here, since there's no CSV amount1 field, %amount1 will produce a-literal "amount1":--fields date,description,csvamount-amount1 %csvamount USD-# Can't interpolate amount1 here-comment %amount1--   When there are multiple field assignments to the same hledger field,-only the last one takes effect.  Here, comment's value will be be B, or-C if "something" is matched, but never A:--comment A-comment B-if something- comment C---File: hledger.info,  Node: How CSV rules are evaluated,  Prev: Referencing other fields,  Up: Tips--13.3.12 How CSV rules are evaluated--------------------------------------Here's how to think of CSV rules being evaluated (if you really need-to).  First,--   * 'include' - all includes are inlined, from top to bottom, depth-     first.  (At each include point the file is inlined and scanned for-     further includes, recursively, before proceeding.)--   Then "global" rules are evaluated, top to bottom.  If a rule is-repeated, the last one wins:--   * 'skip' (at top level)-   * 'date-format'-   * 'newest-first'-   * 'fields' - names the CSV fields, optionally sets up initial-     assignments to hledger fields--   Then for each CSV record in turn:--   * test all 'if' blocks.  If any of them contain a 'end' rule, skip-     all remaining CSV records.  Otherwise if any of them contain a-     'skip' rule, skip that many CSV records.  If there are multiple-     matched 'skip' rules, the first one wins.-   * collect all field assignments at top level and in matched 'if'-     blocks.  When there are multiple assignments for a field, keep only-     the last one.-   * compute a value for each hledger field - either the one that was-     assigned to it (and interpolate the %CSVFIELDNAME references), or a-     default-   * generate a synthetic hledger transaction from these values.--   This is all part of the CSV reader, one of several readers hledger-can use to parse input files.  When all files have been read-successfully, the transactions are passed as input to whichever hledger-command the user specified.---File: hledger.info,  Node: TIMECLOCK FORMAT,  Next: TIMEDOT FORMAT,  Prev: CSV FORMAT,  Up: Top--14 TIMECLOCK FORMAT-*******************--The time logging format of timeclock.el, as read by hledger.--   hledger can read time logs in timeclock format.  As with Ledger,-these are (a subset of) timeclock.el's format, containing clock-in and-clock-out entries as in the example below.  The date is a simple date.-The time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are-optional.  The timezone, if present, must be four digits and is ignored-(currently the time is always interpreted as a local time).--i 2015/03/30 09:00:00 some:account name  optional description after two spaces-o 2015/03/30 09:20:00-i 2015/03/31 22:21:45 another account-o 2015/04/01 02:00:34--   hledger treats each clock-in/clock-out pair as a transaction posting-some number of hours to an account.  Or if the session spans more than-one day, it is split into several transactions, one for each day.  For-the above time log, 'hledger print' generates these journal entries:--$ hledger -f t.timeclock print-2015-03-30 * optional description after two spaces-    (some:account name)         0.33h--2015-03-31 * 22:21-23:59-    (another account)         1.64h--2015-04-01 * 00:00-02:00-    (another account)         2.01h--   Here is a sample.timeclock to download and some queries to try:--$ hledger -f sample.timeclock balance                               # current time balances-$ hledger -f sample.timeclock register -p 2009/3                    # sessions in march 2009-$ hledger -f sample.timeclock register -p weekly --depth 1 --empty  # time summary by week--   To generate time logs, ie to clock in and clock out, you could:--   * use emacs and the built-in timeclock.el, or the extended-     timeclock-x.el and perhaps the extras in ledgerutils.el--   * at the command line, use these bash aliases: 'shell alias ti="echo-     i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o-     `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"'--   * or use the old 'ti' and 'to' scripts in the ledger 2.x repository.-     These rely on a "timeclock" executable which I think is just the-     ledger 2 executable renamed.---File: hledger.info,  Node: TIMEDOT FORMAT,  Next: COMMON TASKS,  Prev: TIMECLOCK FORMAT,  Up: Top--15 TIMEDOT FORMAT-*****************--'timedot' format is hledger's human-friendly time logging format.-Compared to 'timeclock' format, it is--   * convenient for quick, approximate, and retroactive time logging-   * readable: you can see at a glance where time was spent.--   A timedot file contains a series of day entries, which might look-like this:--2021-08-04-hom:errands          .... ....-fos:hledger:timedot  ..         ; docs-per:admin:finance    --   hledger reads this as three time transactions on this day, with each-dot representing a quarter-hour spent:--$ hledger -f a.timedot print   # .timedot file extension activates the timedot reader-2021-08-04 *-    (hom:errands)            2.00--2021-08-04 *-    (fos:hledger:timedot)    0.50--2021-08-04 *-    (per:admin:finance)      0--   A day entry begins with a date line:--   * a non-indented *simple date* (Y-M-D, Y/M/D, or Y.M.D).--   Optionally this can be followed on the same line by--   * a common *transaction description* for this day-   * a common *transaction comment* for this day, after a semicolon-     (';').--   After the date line are zero or more optionally-indented time-transaction lines, consisting of:--   * an *account name* - any word or phrase, usually a hledger-style-     account name.-   * *two or more spaces* - a field separator, required if there is an-     amount (as in journal format).-   * a *timedot amount* - dots representing quarter hours, or a number-     representing hours.-   * an optional *comment* beginning with semicolon.  This is ignored.--   In more detail, timedot amounts can be:--   * *dots*: zero or more period characters, each representing one-     quarter-hour.  Spaces are ignored and can be used for grouping.-     Eg: '.... ..'--   * a *number*, representing hours.  Eg: '1.5'--   * a *number immediately followed by a unit symbol* 's', 'm', 'h',-     'd', 'w', 'mo', or 'y', representing seconds, minutes, hours, days-     weeks, months or years.  Eg '1.5h' or '90m'.  The following-     equivalencies are assumed:-     '60s' = '1m', '60m' = '1h', '24h' = '1d', '7d' = '1w', '30d' =-     '1mo', '365d' = '1y'.  (This unit will not be visible in the-     generated transaction amount, which is always in hours.)--   There is some added flexibility to help with keeping time log data in-the same file as your notes, todo lists, etc.:--   * Lines beginning with '#' or ';', and blank lines, are ignored.--   * Lines not ending with a double-space and amount are parsed as-     transactions with zero amount.  (Most hledger reports hide these by-     default; add -E to see them.)--   * One or more stars ('*') followed by a space, at the start of a-     line, is ignored.  So date lines or time transaction lines can also-     be Org-mode headlines.--   * All Org-mode headlines before the first date line are ignored.--   More examples:--# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.-2016/2/1-inc:client1   .... .... .... .... .... ....-fos:haskell   .... ..-biz:research  .--2016/2/2-inc:client1   .... ....-biz:research  .--2016/2/3-inc:client1   4-fos:hledger   3-biz:research  1--* Time log-** 2020-01-01-*** adm:time  .-*** adm:finance  .--* 2020 Work Diary-** Q1-*** 2020-02-29-**** DONE-0700 yoga-**** UNPLANNED-**** BEGUN-hom:chores- cleaning  ...- water plants-  outdoor - one full watering can-  indoor - light watering-**** TODO-adm:planning: trip-*** LATER--   Reporting:--$ hledger -f a.timedot print date:2016/2/2-2016-02-02 *-    (inc:client1)          2.00--2016-02-02 *-    (biz:research)          0.25--$ hledger -f a.timedot bal --daily --tree-Balance changes in 2016-02-01-2016-02-03:--            ||  2016-02-01d  2016-02-02d  2016-02-03d -============++========================================- biz        ||         0.25         0.25         1.00 -   research ||         0.25         0.25         1.00 - fos        ||         1.50            0         3.00 -   haskell  ||         1.50            0            0 -   hledger  ||            0            0         3.00 - inc        ||         6.00         2.00         4.00 -   client1  ||         6.00         2.00         4.00 -------------++-----------------------------------------            ||         7.75         2.25         8.00 --   Using period instead of colon as account name separator:--2016/2/4-fos.hledger.timedot  4-fos.ledger           ..--$ hledger -f a.timedot --alias /\\./=: bal --tree-                4.50  fos-                4.00    hledger:timedot-                0.50    ledger----------------------                4.50--   A sample.timedot file.---File: hledger.info,  Node: COMMON TASKS,  Next: LIMITATIONS,  Prev: TIMEDOT FORMAT,  Up: Top--16 COMMON TASKS-***************--Here are some quick examples of how to do some basic tasks with hledger.-For more details, see the reference section below, the-hledger_journal(5) manual, or the more extensive docs at-https://hledger.org.--* Menu:--* Getting help::-* Constructing command lines::-* Starting a journal file::-* Setting opening balances::-* Recording transactions::-* Reconciling::-* Reporting::-* Migrating to a new file::---File: hledger.info,  Node: Getting help,  Next: Constructing command lines,  Up: COMMON TASKS--16.1 Getting help-=================--$ hledger                 # show available commands-$ hledger --help          # show common options-$ hledger CMD --help      # show common and command options, and command help-$ hledger help            # show available manuals/topics-$ hledger help hledger    # show hledger manual as info/man/text (auto-chosen)-$ hledger help journal --man  # show the journal manual as a man page-$ hledger help --help     # show more detailed help for the help command--   Find more docs, chat, mail list, reddit, issue tracker:-https://hledger.org#help-feedback---File: hledger.info,  Node: Constructing command lines,  Next: Starting a journal file,  Prev: Getting help,  Up: COMMON TASKS--16.2 Constructing command lines-===============================--hledger has an extensive and powerful command line interface.  We strive-to keep it simple and ergonomic, but you may run into one of the-confusing real world details described in OPTIONS, below.  If that-happens, here are some tips that may help:--   * command-specific options must go after the command (it's fine to-     put all options there) ('hledger CMD OPTS ARGS')-   * running add-on executables directly simplifies command line parsing-     ('hledger-ui OPTS ARGS')-   * enclose "problematic" args in single quotes-   * if needed, also add a backslash to hide regular expression-     metacharacters from the shell-   * to see how a misbehaving command is being parsed, add '--debug=2'.---File: hledger.info,  Node: Starting a journal file,  Next: Setting opening balances,  Prev: Constructing command lines,  Up: COMMON TASKS--16.3 Starting a journal file-============================--hledger looks for your accounting data in a journal file,-'$HOME/.hledger.journal' by default:--$ hledger stats-The hledger journal file "/Users/simon/.hledger.journal" was not found.-Please create it first, eg with "hledger add" or a text editor.-Or, specify an existing journal file with -f or LEDGER_FILE.--   You can override this by setting the 'LEDGER_FILE' environment-variable.  It's a good practice to keep this important file under-version control, and to start a new file each year.  So you could do-something like this:--$ mkdir ~/finance-$ cd ~/finance-$ git init-Initialized empty Git repository in /Users/simon/finance/.git/-$ touch 2020.journal-$ echo "export LEDGER_FILE=$HOME/finance/2020.journal" >> ~/.bashrc-$ source ~/.bashrc-$ hledger stats-Main file                : /Users/simon/finance/2020.journal-Included files           : -Transactions span        :  to  (0 days)-Last transaction         : none-Transactions             : 0 (0.0 per day)-Transactions last 30 days: 0 (0.0 per day)-Transactions last 7 days : 0 (0.0 per day)-Payees/descriptions      : 0-Accounts                 : 0 (depth 0)-Commodities              : 0 ()-Market prices            : 0 ()---File: hledger.info,  Node: Setting opening balances,  Next: Recording transactions,  Prev: Starting a journal file,  Up: COMMON TASKS--16.4 Setting opening balances-=============================--Pick a starting date for which you can look up the balances of some-real-world assets (bank accounts, wallet..)  and liabilities (credit-cards..).--   To avoid a lot of data entry, you may want to start with just one or-two accounts, like your checking account or cash wallet; and pick a-recent starting date, like today or the start of the week.  You can-always come back later and add more accounts and older transactions, eg-going back to january 1st.--   Add an opening balances transaction to the journal, declaring the-balances on this date.  Here are two ways to do it:--   * The first way: open the journal in any text editor and save an-     entry like this:--     2020-01-01 * opening balances-         assets:bank:checking                $1000   = $1000-         assets:bank:savings                 $2000   = $2000-         assets:cash                          $100   = $100-         liabilities:creditcard               $-50   = $-50-         equity:opening/closing balances--     These are start-of-day balances, ie whatever was in the account at-     the end of the previous day.--     The * after the date is an optional status flag.  Here it means-     "cleared & confirmed".--     The currency symbols are optional, but usually a good idea as-     you'll be dealing with multiple currencies sooner or later.--     The = amounts are optional balance assertions, providing extra-     error checking.--   * The second way: run 'hledger add' and follow the prompts to record-     a similar transaction:--     $ hledger add-     Adding transactions to journal file /Users/simon/finance/2020.journal-     Any command line arguments will be used as defaults.-     Use tab key to complete, readline keys to edit, enter to accept defaults.-     An optional (CODE) may follow transaction dates.-     An optional ; COMMENT may follow descriptions or amounts.-     If you make a mistake, enter < at any prompt to go one step backward.-     To end a transaction, enter . when prompted.-     To quit, enter . at a date prompt or press control-d or control-c.-     Date [2020-02-07]: 2020-01-01-     Description: * opening balances-     Account 1: assets:bank:checking-     Amount  1: $1000-     Account 2: assets:bank:savings-     Amount  2 [$-1000]: $2000-     Account 3: assets:cash-     Amount  3 [$-3000]: $100-     Account 4: liabilities:creditcard-     Amount  4 [$-3100]: $-50-     Account 5: equity:opening/closing balances-     Amount  5 [$-3050]: -     Account 6 (or . or enter to finish this transaction): .-     2020-01-01 * opening balances-         assets:bank:checking                      $1000-         assets:bank:savings                       $2000-         assets:cash                                $100-         liabilities:creditcard                     $-50-         equity:opening/closing balances          $-3050-     -     Save this transaction to the journal ? [y]: -     Saved.-     Starting the next transaction (. or ctrl-D/ctrl-C to quit)-     Date [2020-01-01]: .--   If you're using version control, this could be a good time to commit-the journal.  Eg:--$ git commit -m 'initial balances' 2020.journal---File: hledger.info,  Node: Recording transactions,  Next: Reconciling,  Prev: Setting opening balances,  Up: COMMON TASKS--16.5 Recording transactions-===========================--As you spend or receive money, you can record these transactions using-one of the methods above (text editor, hledger add) or by using the-hledger-iadd or hledger-web add-ons, or by using the import command to-convert CSV data downloaded from your bank.--   Here are some simple transactions, see the hledger_journal(5) manual-and hledger.org for more ideas:--2020/1/10 * gift received-  assets:cash   $20-  income:gifts--2020.1.12 * farmers market-  expenses:food    $13-  assets:cash--2020-01-15 paycheck-  income:salary-  assets:bank:checking    $1000---File: hledger.info,  Node: Reconciling,  Next: Reporting,  Prev: Recording transactions,  Up: COMMON TASKS--16.6 Reconciling-================--Periodically you should reconcile - compare your hledger-reported-balances against external sources of truth, like bank statements or your-bank's website - to be sure that your ledger accurately represents the-real-world balances (and, that the real-world institutions have not made-a mistake!).  This gets easy and fast with (1) practice and (2)-frequency.  If you do it daily, it can take 2-10 minutes.  If you let it-pile up, expect it to take longer as you hunt down errors and-discrepancies.--   A typical workflow:--  1. Reconcile cash.  Count what's in your wallet.  Compare with what-     hledger reports ('hledger bal cash').  If they are different, try-     to remember the missing transaction, or look for the error in the-     already-recorded transactions.  A register report can be helpful-     ('hledger reg cash').  If you can't find the error, add an-     adjustment transaction.  Eg if you have $105 after the above, and-     can't explain the missing $2, it could be:--     2020-01-16 * adjust cash-         assets:cash    $-2 = $105-         expenses:misc--  2. Reconcile checking.  Log in to your bank's website.  Compare-     today's (cleared) balance with hledger's cleared balance ('hledger-     bal checking -C').  If they are different, track down the error or-     record the missing transaction(s) or add an adjustment transaction,-     similar to the above.  Unlike the cash case, you can usually-     compare the transaction history and running balance from your bank-     with the one reported by 'hledger reg checking -C'.  This will be-     easier if you generally record transaction dates quite similar to-     your bank's clearing dates.--  3. Repeat for other asset/liability accounts.--   Tip: instead of the register command, use hledger-ui to see a-live-updating register while you edit the journal: 'hledger-ui --watch---register checking -C'--   After reconciling, it could be a good time to mark the reconciled-transactions' status as "cleared and confirmed", if you want to track-that, by adding the '*' marker.  Eg in the paycheck transaction above,-insert '*' between '2020-01-15' and 'paycheck'--   If you're using version control, this can be another good time to-commit:--$ git commit -m 'txns' 2020.journal---File: hledger.info,  Node: Reporting,  Next: Migrating to a new file,  Prev: Reconciling,  Up: COMMON TASKS--16.7 Reporting-==============--Here are some basic reports.--   Show all transactions:--$ hledger print-2020-01-01 * opening balances-    assets:bank:checking                      $1000-    assets:bank:savings                       $2000-    assets:cash                                $100-    liabilities:creditcard                     $-50-    equity:opening/closing balances          $-3050--2020-01-10 * gift received-    assets:cash              $20-    income:gifts--2020-01-12 * farmers market-    expenses:food             $13-    assets:cash--2020-01-15 * paycheck-    income:salary-    assets:bank:checking           $1000--2020-01-16 * adjust cash-    assets:cash               $-2 = $105-    expenses:misc--   Show account names, and their hierarchy:--$ hledger accounts --tree-assets-  bank-    checking-    savings-  cash-equity-  opening/closing balances-expenses-  food-  misc-income-  gifts-  salary-liabilities-  creditcard--   Show all account totals:--$ hledger balance-               $4105  assets-               $4000    bank-               $2000      checking-               $2000      savings-                $105    cash-              $-3050  equity:opening/closing balances-                 $15  expenses-                 $13    food-                  $2    misc-              $-1020  income-                $-20    gifts-              $-1000    salary-                $-50  liabilities:creditcard----------------------                   0--   Show only asset and liability balances, as a flat list, limited to-depth 2:--$ hledger bal assets liabilities --flat -2-               $4000  assets:bank-                $105  assets:cash-                $-50  liabilities:creditcard----------------------               $4055--   Show the same thing without negative numbers, formatted as a simple-balance sheet:--$ hledger bs --flat -2-Balance Sheet 2020-01-16--                        || 2020-01-16 -========================++============- Assets                 ||            -------------------------++------------- assets:bank            ||      $4000 - assets:cash            ||       $105 -------------------------++-------------                        ||      $4105 -========================++============- Liabilities            ||            -------------------------++------------- liabilities:creditcard ||        $50 -------------------------++-------------                        ||        $50 -========================++============- Net:                   ||      $4055 --   The final total is your "net worth" on the end date.  (Or use 'bse'-for a full balance sheet with equity.)--   Show income and expense totals, formatted as an income statement:--hledger is -Income Statement 2020-01-01-2020-01-16--               || 2020-01-01-2020-01-16 -===============++=======================- Revenues      ||                       ----------------++------------------------ income:gifts  ||                   $20 - income:salary ||                 $1000 ----------------++------------------------               ||                 $1020 -===============++=======================- Expenses      ||                       ----------------++------------------------ expenses:food ||                   $13 - expenses:misc ||                    $2 ----------------++------------------------               ||                   $15 -===============++=======================- Net:          ||                 $1005 --   The final total is your net income during this period.--   Show transactions affecting your wallet, with running total:--$ hledger register cash-2020-01-01 opening balances     assets:cash                   $100          $100-2020-01-10 gift received        assets:cash                    $20          $120-2020-01-12 farmers market       assets:cash                   $-13          $107-2020-01-16 adjust cash          assets:cash                    $-2          $105--   Show weekly posting counts as a bar chart:--$ hledger activity -W-2019-12-30 *****-2020-01-06 ****-2020-01-13 ****---File: hledger.info,  Node: Migrating to a new file,  Prev: Reporting,  Up: COMMON TASKS--16.8 Migrating to a new file-============================--At the end of the year, you may want to continue your journal in a new-file, so that old transactions don't slow down or clutter your reports,-and to help ensure the integrity of your accounting history.  See the-close command.--   If using version control, don't forget to 'git add' the new file.---File: hledger.info,  Node: LIMITATIONS,  Next: TROUBLESHOOTING,  Prev: COMMON TASKS,  Up: Top--17 LIMITATIONS-**************--The need to precede add-on command options with '--' when invoked from-hledger is awkward.--   When input data contains non-ascii characters, a suitable system-locale must be configured (or there will be an unhelpful error).  Eg on-POSIX, set LANG to something other than C.--   In a Microsoft Windows CMD window, non-ascii characters and colours-are not supported.--   On Windows, non-ascii characters may not display correctly when-running a hledger built in CMD in MSYS/CYGWIN, or vice-versa.--   In a Cygwin/MSYS/Mintty window, the tab key is not supported in-hledger add.--   Not all of Ledger's journal file syntax is supported.  See file-format differences.--   On large data files, hledger is slower and uses more memory than-Ledger.---File: hledger.info,  Node: TROUBLESHOOTING,  Prev: LIMITATIONS,  Up: Top--18 TROUBLESHOOTING-******************--Here are some issues you might encounter when you run hledger (and-remember you can also seek help from the IRC channel, mail list or bug-tracker):--   *Successfully installed, but "No command 'hledger' found"*-stack and cabal install binaries into a special directory, which should-be added to your PATH environment variable.  Eg on unix-like systems,-that is ~/.local/bin and ~/.cabal/bin respectively.--   *I set a custom LEDGER_FILE, but hledger is still using the default-file*-'LEDGER_FILE' should be a real environment variable, not just a shell-variable.  The command 'env | grep LEDGER_FILE' should show it.  You may-need to use 'export'.  Here's an explanation.--   *Getting errors like "Illegal byte sequence" or "Invalid or-incomplete multibyte or wide character" or "commitAndReleaseBuffer:-invalid argument (invalid character)"*-Programs compiled with GHC (hledger, haskell build tools, etc.)  need to-have a UTF-8-aware locale configured in the environment, otherwise they-will fail with these kinds of errors when they encounter non-ascii-characters.--   To fix it, set the LANG environment variable to some locale which-supports UTF-8.  The locale you choose must be installed on your system.--   Here's an example of setting LANG temporarily, on Ubuntu GNU/Linux:--$ file my.journal-my.journal: UTF-8 Unicode text         # the file is UTF8-encoded-$ echo $LANG-C                                      # LANG is set to the default locale, which does not support UTF8-$ locale -a                            # which locales are installed ?-C-en_US.utf8                             # here's a UTF8-aware one we can use-POSIX-$ LANG=en_US.utf8 hledger -f my.journal print   # ensure it is used for this command--   If available, 'C.UTF-8' will also work.  If your preferred locale-isn't listed by 'locale -a', you might need to install it.  Eg on-Ubuntu/Debian:--$ apt-get install language-pack-fr-$ locale -a-C-en_US.utf8-fr_BE.utf8-fr_CA.utf8-fr_CH.utf8-fr_FR.utf8-fr_LU.utf8-POSIX-$ LANG=fr_FR.utf8 hledger -f my.journal print--   Here's how you could set it permanently, if you use a bash shell:--$ echo "export LANG=en_US.utf8" >>~/.bash_profile-$ bash --login--   Exact spelling and capitalisation may be important.  Note the-difference on MacOS ('UTF-8', not 'utf8').  Some platforms (eg ubuntu)-allow variant spellings, but others (eg macos) require it to be exact:--$ locale -a | grep -iE en_us.*utf-en_US.UTF-8-$ LANG=en_US.UTF-8 hledger -f my.journal print---Tag Table:-Node: Top208-Node: OPTIONS2605-Ref: #options2706-Node: General options2848-Ref: #general-options2973-Node: Command options7186-Ref: #command-options7337-Node: Command arguments7737-Ref: #command-arguments7895-Node: Special characters8775-Ref: #special-characters8938-Node: Single escaping shell metacharacters9101-Ref: #single-escaping-shell-metacharacters9342-Node: Double escaping regular expression metacharacters9945-Ref: #double-escaping-regular-expression-metacharacters10256-Node: Triple escaping for add-on commands10782-Ref: #triple-escaping-for-add-on-commands11042-Node: Less escaping11686-Ref: #less-escaping11840-Node: Unicode characters12164-Ref: #unicode-characters12329-Node: Regular expressions13741-Ref: #regular-expressions13881-Node: ENVIRONMENT15617-Ref: #environment15733-Node: DATA FILES17225-Ref: #data-files17344-Node: Data formats17883-Ref: #data-formats18001-Node: Multiple files19395-Ref: #multiple-files19537-Node: Strict mode20006-Ref: #strict-mode20121-Node: TIME PERIODS20827-Ref: #time-periods20944-Node: Smart dates21042-Ref: #smart-dates21168-Node: Report start & end date22705-Ref: #report-start-end-date22880-Node: Report intervals24547-Ref: #report-intervals24715-Node: Period expressions26454-Ref: #period-expressions26594-Node: Period expressions with a report interval28325-Ref: #period-expressions-with-a-report-interval28557-Node: More complex report intervals29638-Ref: #more-complex-report-intervals29887-Node: Intervals with custom start date30522-Ref: #intervals-with-custom-start-date30754-Node: Periods or dates ?32328-Ref: #periods-or-dates32530-Node: Events on multiple weekdays32972-Ref: #events-on-multiple-weekdays33151-Node: DEPTH34014-Ref: #depth34114-Node: QUERIES34448-Ref: #queries34547-Node: Query types35488-Ref: #query-types35607-Node: Combining query terms38279-Ref: #combining-query-terms38454-Node: Queries and command options39257-Ref: #queries-and-command-options39460-Node: Queries and account aliases39709-Ref: #queries-and-account-aliases39912-Node: Queries and valuation40032-Ref: #queries-and-valuation40225-Node: Querying with account aliases40454-Ref: #querying-with-account-aliases40663-Node: Querying with cost or value40793-Ref: #querying-with-cost-or-value40968-Node: COSTING41269-Ref: #costing41372-Node: VALUATION41646-Ref: #valuation41754-Node: -V Value42521-Ref: #v-value42645-Node: -X Value in specified commodity42840-Ref: #x-value-in-specified-commodity43033-Node: Valuation date43182-Ref: #valuation-date43344-Node: Market prices43781-Ref: #market-prices43963-Node: --infer-market-prices market prices from transactions45146-Ref: #infer-market-prices-market-prices-from-transactions45413-Node: Valuation commodity46769-Ref: #valuation-commodity46980-Node: Simple valuation examples48206-Ref: #simple-valuation-examples48402-Node: --value Flexible valuation49061-Ref: #value-flexible-valuation49263-Node: More valuation examples50907-Ref: #more-valuation-examples51114-Node: Interaction of valuation and queries53113-Ref: #interaction-of-valuation-and-queries53352-Node: Effect of valuation on reports53824-Ref: #effect-of-valuation-on-reports54019-Node: PIVOTING61716-Ref: #pivoting61821-Node: OUTPUT63497-Ref: #output63599-Node: Output destination63690-Ref: #output-destination63824-Node: Output styling64481-Ref: #output-styling64629-Node: Output format65386-Ref: #output-format65530-Node: CSV output66894-Ref: #csv-output67012-Node: HTML output67115-Ref: #html-output67255-Node: JSON output67349-Ref: #json-output67489-Node: SQL output68406-Ref: #sql-output68524-Node: Commodity styles69025-Ref: #commodity-styles69152-Node: COMMANDS69928-Ref: #commands70040-Node: accounts73405-Ref: #accounts73505-Node: activity74201-Ref: #activity74313-Node: add74696-Ref: #add74799-Node: aregister77592-Ref: #aregister77706-Node: aregister and custom posting dates80071-Ref: #aregister-and-custom-posting-dates80237-Node: balance80789-Ref: #balance80908-Node: balance features81901-Ref: #balance-features82041-Node: Simple balance report83965-Ref: #simple-balance-report84147-Node: Filtered balance report85627-Ref: #filtered-balance-report85814-Node: List or tree mode86141-Ref: #list-or-tree-mode86309-Node: Depth limiting87654-Ref: #depth-limiting87820-Node: Dropping top-level accounts88421-Ref: #dropping-top-level-accounts88623-Node: Multi-period balance report88933-Ref: #multi-period-balance-report89146-Node: Showing declared accounts91421-Ref: #showing-declared-accounts91614-Node: Data layout92145-Ref: #data-layout92300-Node: Sorting by amount100240-Ref: #sorting-by-amount100395-Node: Percentages101065-Ref: #percentages101223-Node: Balance change end balance102184-Ref: #balance-change-end-balance102377-Node: Balance report types103805-Ref: #balance-report-types103995-Node: Useful balance reports108274-Ref: #useful-balance-reports108455-Node: Budget report109540-Ref: #budget-report109724-Node: Budget report start date114999-Ref: #budget-report-start-date115177-Node: Budgets and subaccounts116509-Ref: #budgets-and-subaccounts116716-Node: Selecting budget goals120156-Ref: #selecting-budget-goals120328-Node: Customising single-period balance reports121362-Ref: #customising-single-period-balance-reports121571-Node: balancesheet123746-Ref: #balancesheet123884-Node: balancesheetequity125183-Ref: #balancesheetequity125334-Node: cashflow126714-Ref: #cashflow126838-Node: check127984-Ref: #check128089-Node: Basic checks128723-Ref: #basic-checks128841-Node: Strict checks129392-Ref: #strict-checks129533-Node: Other checks129969-Ref: #other-checks130109-Node: Custom checks130466-Ref: #custom-checks130586-Node: close131003-Ref: #close131107-Node: close and prices133198-Ref: #close-and-prices133327-Node: close date133722-Ref: #close-date133906-Node: Example close asset/liability accounts for file transition134663-Ref: #example-close-assetliability-accounts-for-file-transition134964-Node: Hiding opening/closing transactions135823-Ref: #hiding-openingclosing-transactions136094-Node: close and balance assertions137471-Ref: #close-and-balance-assertions137729-Node: Example close revenue/expense accounts to retained earnings139083-Ref: #example-close-revenueexpense-accounts-to-retained-earnings139361-Node: codes140251-Ref: #codes140361-Node: commodities141073-Ref: #commodities141202-Node: descriptions141284-Ref: #descriptions141414-Node: diff141718-Ref: #diff141826-Node: files142873-Ref: #files142975-Node: help143122-Ref: #help143224-Node: import144042-Ref: #import144158-Node: Deduplication145023-Ref: #deduplication145148-Node: Import testing147042-Ref: #import-testing147207-Node: Importing balance assignments147695-Ref: #importing-balance-assignments147901-Node: Commodity display styles148550-Ref: #commodity-display-styles148723-Node: incomestatement148852-Ref: #incomestatement148987-Node: notes150292-Ref: #notes150407-Node: payees150775-Ref: #payees150883-Node: prices151409-Ref: #prices151517-Node: print151886-Ref: #print151998-Node: print-unique157313-Ref: #print-unique157441-Node: register157726-Ref: #register157855-Node: Custom register output162301-Ref: #custom-register-output162432-Node: register-match163769-Ref: #register-match163905-Node: rewrite164256-Ref: #rewrite164373-Node: Re-write rules in a file166279-Ref: #re-write-rules-in-a-file166442-Node: Diff output format167591-Ref: #diff-output-format167774-Node: rewrite vs print --auto168866-Ref: #rewrite-vs.-print---auto169026-Node: roi169582-Ref: #roi169682-Node: Spaces and special characters in --inv and --pnl171368-Ref: #spaces-and-special-characters-in---inv-and---pnl171608-Node: Semantics of --inv and --pnl172096-Ref: #semantics-of---inv-and---pnl172335-Node: IRR and TWR explained174185-Ref: #irr-and-twr-explained174345-Node: stats177413-Ref: #stats177514-Node: tags178894-Ref: #tags178994-Node: test179513-Ref: #test179629-Node: About add-on commands180376-Ref: #about-add-on-commands180513-Node: JOURNAL FORMAT181644-Ref: #journal-format181772-Node: Transactions183999-Ref: #transactions184114-Node: Dates185128-Ref: #dates185244-Node: Simple dates185309-Ref: #simple-dates185429-Node: Secondary dates185938-Ref: #secondary-dates186086-Node: Posting dates187422-Ref: #posting-dates187545-Node: Status188917-Ref: #status189027-Node: Code190735-Ref: #code190847-Node: Description191079-Ref: #description191207-Node: Payee and note191527-Ref: #payee-and-note191635-Node: Comments191970-Ref: #comments192092-Node: Tags193286-Ref: #tags-1193397-Node: Postings194790-Ref: #postings194914-Node: Virtual postings195940-Ref: #virtual-postings196051-Node: Account names197356-Ref: #account-names197493-Node: Amounts197981-Ref: #amounts198118-Node: Decimal marks digit group marks199103-Ref: #decimal-marks-digit-group-marks199280-Node: Commodity200301-Ref: #commodity200490-Node: Directives influencing number parsing and display201442-Ref: #directives-influencing-number-parsing-and-display201703-Node: Commodity display style202196-Ref: #commodity-display-style202404-Node: Rounding204599-Ref: #rounding204719-Node: Transaction prices205131-Ref: #transaction-prices205297-Node: Lot prices lot dates207728-Ref: #lot-prices-lot-dates207911-Node: Balance assertions208399-Ref: #balance-assertions208577-Node: Assertions and ordering209610-Ref: #assertions-and-ordering209792-Node: Assertions and included files210492-Ref: #assertions-and-included-files210729-Node: Assertions and multiple -f options211062-Ref: #assertions-and-multiple--f-options211312-Node: Assertions and commodities211444-Ref: #assertions-and-commodities211670-Node: Assertions and prices212827-Ref: #assertions-and-prices213035-Node: Assertions and subaccounts213475-Ref: #assertions-and-subaccounts213698-Node: Assertions and virtual postings214022-Ref: #assertions-and-virtual-postings214258-Node: Assertions and precision214400-Ref: #assertions-and-precision214587-Node: Balance assignments214854-Ref: #balance-assignments215024-Node: Balance assignments and prices216188-Ref: #balance-assignments-and-prices216354-Node: Directives216578-Ref: #directives216741-Node: Directives and multiple files221233-Ref: #directives-and-multiple-files221429-Node: Comment blocks222121-Ref: #comment-blocks222298-Node: Including other files222474-Ref: #including-other-files222648-Node: Default year223572-Ref: #default-year223730-Node: Declaring payees224137-Ref: #declaring-payees224308-Node: Declaring the decimal mark224554-Ref: #declaring-the-decimal-mark224754-Node: Declaring commodities225151-Ref: #declaring-commodities225342-Node: Commodity error checking227860-Ref: #commodity-error-checking228010-Node: Default commodity228267-Ref: #default-commodity228447-Node: Declaring market prices229563-Ref: #declaring-market-prices229752-Node: Declaring accounts230565-Ref: #declaring-accounts230745-Node: Account error checking231947-Ref: #account-error-checking232113-Node: Account comments233292-Ref: #account-comments233476-Node: Account subdirectives233900-Ref: #account-subdirectives234085-Node: Account types234398-Ref: #account-types234572-Node: Auto-detected account types235895-Ref: #auto-detected-account-types236050-Node: Account display order237285-Ref: #account-display-order237445-Node: Rewriting accounts238596-Ref: #rewriting-accounts238775-Node: Basic aliases239532-Ref: #basic-aliases239668-Node: Regex aliases240412-Ref: #regex-aliases240574-Node: Combining aliases241293-Ref: #combining-aliases241476-Node: Aliases and multiple files242752-Ref: #aliases-and-multiple-files242951-Node: end aliases243530-Ref: #end-aliases243677-Node: Default parent account243826-Ref: #default-parent-account244016-Node: Periodic transactions244900-Ref: #periodic-transactions245083-Node: Periodic rule syntax247000-Ref: #periodic-rule-syntax247200-Node: Two spaces between period expression and description!247904-Ref: #two-spaces-between-period-expression-and-description248217-Node: Forecasting with periodic transactions248901-Ref: #forecasting-with-periodic-transactions249200-Node: Budgeting with periodic transactions251971-Ref: #budgeting-with-periodic-transactions252204-Node: Auto postings252613-Ref: #auto-postings252749-Node: Auto postings and multiple files254928-Ref: #auto-postings-and-multiple-files255126-Node: Auto postings and dates255335-Ref: #auto-postings-and-dates255603-Node: Auto postings and transaction balancing / inferred amounts / balance assertions255778-Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions256123-Node: Auto posting tags256626-Ref: #auto-posting-tags256835-Node: CSV FORMAT257471-Ref: #csv-format257599-Node: Examples260228-Ref: #examples260331-Node: Basic260539-Ref: #basic260641-Node: Bank of Ireland261183-Ref: #bank-of-ireland261320-Node: Amazon262782-Ref: #amazon262902-Node: Paypal264621-Ref: #paypal264717-Node: CSV rules272361-Ref: #csv-rules272479-Node: skip272812-Ref: #skip272912-Node: fields list273287-Ref: #fields-list273426-Node: field assignment274992-Ref: #field-assignment275144-Node: Field names276179-Ref: #field-names276319-Node: date field276699-Ref: #date-field276819-Node: date2 field276867-Ref: #date2-field277010-Node: status field277066-Ref: #status-field277211-Node: code field277260-Ref: #code-field277407-Node: description field277452-Ref: #description-field277614-Node: comment field277673-Ref: #comment-field277830-Node: account field278141-Ref: #account-field278293-Node: amount field278868-Ref: #amount-field279019-Node: currency field280264-Ref: #currency-field280419-Node: balance field280676-Ref: #balance-field280810-Node: separator281182-Ref: #separator281314-Node: if block281854-Ref: #if-block281981-Node: Matching the whole record282382-Ref: #matching-the-whole-record282559-Node: Matching individual fields283362-Ref: #matching-individual-fields283568-Node: Combining matchers283792-Ref: #combining-matchers283990-Node: Rules applied on successful match284303-Ref: #rules-applied-on-successful-match284496-Node: if table285150-Ref: #if-table285271-Node: end287009-Ref: #end287123-Node: date-format287347-Ref: #date-format287481-Node: decimal-mark288477-Ref: #decimal-mark288624-Node: newest-first288963-Ref: #newest-first289106-Node: include289789-Ref: #include289922-Node: balance-type290366-Ref: #balance-type290488-Node: Tips291188-Ref: #tips291279-Node: Rapid feedback291578-Ref: #rapid-feedback291697-Node: Valid CSV292149-Ref: #valid-csv292281-Node: File Extension292473-Ref: #file-extension292627-Node: Reading multiple CSV files293056-Ref: #reading-multiple-csv-files293243-Node: Valid transactions293484-Ref: #valid-transactions293664-Node: Deduplicating importing294292-Ref: #deduplicating-importing294473-Node: Setting amounts295506-Ref: #setting-amounts295663-Node: Amount signs298104-Ref: #amount-signs298258-Node: Setting currency/commodity298945-Ref: #setting-currencycommodity299133-Node: Amount decimal places300307-Ref: #amount-decimal-places300499-Node: Referencing other fields300811-Ref: #referencing-other-fields301010-Node: How CSV rules are evaluated301907-Ref: #how-csv-rules-are-evaluated302082-Node: TIMECLOCK FORMAT303533-Ref: #timeclock-format303673-Node: TIMEDOT FORMAT305734-Ref: #timedot-format305872-Node: COMMON TASKS310434-Ref: #common-tasks310563-Node: Getting help310970-Ref: #getting-help311104-Node: Constructing command lines311657-Ref: #constructing-command-lines311851-Node: Starting a journal file312548-Ref: #starting-a-journal-file312748-Node: Setting opening balances313936-Ref: #setting-opening-balances314134-Node: Recording transactions317275-Ref: #recording-transactions317457-Node: Reconciling318013-Ref: #reconciling318158-Node: Reporting320415-Ref: #reporting320557-Node: Migrating to a new file324556-Ref: #migrating-to-a-new-file324706-Node: LIMITATIONS325005-Ref: #limitations325133-Node: TROUBLESHOOTING325876-Ref: #troubleshooting325991+manual is for hledger 1.25.++   'hledger'++   'hledger [-f FILE] COMMAND [OPTIONS] [ARGS]'++   'hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS]'++   hledger is a reliable, cross-platform set of programs for tracking+money, time, or any other commodity, using double-entry accounting and a+simple, editable file format.  hledger is inspired by and largely+compatible with ledger(1).++   The basic function of the hledger CLI is to read a plain text file+describing financial transactions (in accounting terms, a general+journal) and print useful reports on standard output, or export them as+CSV. hledger can also read some other file formats such as CSV files,+translating them to journal format.  Additionally, hledger lists other+hledger-* executables found in the user's $PATH and can invoke them as+subcommands.++   hledger reads data from one or more files in hledger journal,+timeclock, timedot, or CSV format specified with '-f', or+'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps+'C:/Users/USER/.hledger.journal').  If using '$LEDGER_FILE', note this+must be a real environment variable, not a shell variable.  You can+specify standard input with '-f-'.++   Transactions are dated movements of money between two (or more) named+accounts, and are recorded with journal entries like this:++2015/10/16 bought food+ expenses:food          $10+ assets:cash++   Most users use a text editor to edit the journal, usually with an+editor mode such as ledger-mode for added convenience.  hledger's+interactive add command is another way to record new transactions.+hledger never changes existing transactions.++   To get started, you can either save some entries like the above in+'~/.hledger.journal', or run 'hledger add' and follow the prompts.  Then+try some commands like 'hledger print' or 'hledger balance'.  Run+'hledger' with no arguments for a list of commands.++* Menu:++* OPTIONS::+* ENVIRONMENT::+* DATA FILES::+* TIME PERIODS::+* DEPTH::+* QUERIES::+* CONVERSION & COST::+* VALUATION::+* PIVOTING::+* OUTPUT::+* COMMANDS::+* JOURNAL FORMAT::+* CSV FORMAT::+* TIMECLOCK FORMAT::+* TIMEDOT FORMAT::+* COMMON TASKS::+* LIMITATIONS::+* TROUBLESHOOTING::+++File: hledger.info,  Node: OPTIONS,  Next: ENVIRONMENT,  Prev: Top,  Up: Top++1 OPTIONS+*********++* Menu:++* General options::+* Command options::+* Command arguments::+* Special characters::+* Unicode characters::+* Regular expressions::+++File: hledger.info,  Node: General options,  Next: Command options,  Up: OPTIONS++1.1 General options+===================++To see general usage help, including general options which are supported+by most hledger commands, run 'hledger -h'.++   General help options:++'-h --help'++     show general or COMMAND help+'--man'++     show general or COMMAND user manual with man+'--info'++     show general or COMMAND user manual with info+'--version'++     show general or ADDONCMD version+'--debug[=N]'++     show debug output (levels 1-9, default: 1)++   General input options:++'-f FILE --file=FILE'++     use a different input file.  For stdin, use - (default:+     '$LEDGER_FILE' or '$HOME/.hledger.journal')+'--rules-file=RULESFILE'++     Conversion rules file to use when reading CSV (default: FILE.rules)+'--separator=CHAR'++     Field separator to expect when reading CSV (default: ',')+'--alias=OLD=NEW'++     rename accounts named OLD to NEW+'--anon'++     anonymize accounts and payees+'--pivot FIELDNAME'++     use some other field or tag for the account name+'-I --ignore-assertions'++     disable balance assertion checks (note: does not disable balance+     assignments)+'-s --strict'++     do extra error checking (check that all posted accounts are+     declared)++   General reporting options:++'-b --begin=DATE'++     include postings/txns on or after this date (will be adjusted to+     preceding subperiod start when using a report interval)+'-e --end=DATE'++     include postings/txns before this date (will be adjusted to+     following subperiod end when using a report interval)+'-D --daily'++     multiperiod/multicolumn report by day+'-W --weekly'++     multiperiod/multicolumn report by week+'-M --monthly'++     multiperiod/multicolumn report by month+'-Q --quarterly'++     multiperiod/multicolumn report by quarter+'-Y --yearly'++     multiperiod/multicolumn report by year+'-p --period=PERIODEXP'++     set start date, end date, and/or reporting interval all at once+     using period expressions syntax+'--date2'++     match the secondary date instead (see command help for other+     effects)+'--today=DATE'++     override today's date (affects relative smart dates, for+     tests/examples)+'-U --unmarked'++     include only unmarked postings/txns (can combine with -P or -C)+'-P --pending'++     include only pending postings/txns+'-C --cleared'++     include only cleared postings/txns+'-R --real'++     include only non-virtual postings+'-NUM --depth=NUM'++     hide/aggregate accounts or postings more than NUM levels deep+'-E --empty'++     show items with zero amount, normally hidden (and vice-versa in+     hledger-ui/hledger-web)+'-B --cost'++     convert amounts to their cost/selling amount at transaction time+'-V --market'++     convert amounts to their market value in default valuation+     commodities+'-X --exchange=COMM'++     convert amounts to their market value in commodity COMM+'--value'++     convert amounts to cost or market value, more flexibly than+     -B/-V/-X+'--infer-market-prices'++     use transaction prices (recorded with @ or @@) as additional market+     prices, as if they were P directives+'--auto'++     apply automated posting rules to modify transactions.+'--forecast'++     generate future transactions from periodic transaction rules, for+     the next 6 months or till report end date.  In hledger-ui, also+     make ordinary future transactions visible.+'--commodity-style'++     Override the commodity style in the output for the specified+     commodity.  For example 'EUR1.000,00'.+'--color=WHEN (or --colour=WHEN)'++     Should color-supporting commands use ANSI color codes in text+     output.  'auto' (default): whenever stdout seems to be a+     color-supporting terminal.  'always' or 'yes': always, useful eg+     when piping output into 'less -R'. 'never' or 'no': never.  A+     NO_COLOR environment variable overrides this.+'--pretty[=WHEN]'++     Show prettier output, e.g.  using unicode box-drawing characters.+     Accepts 'yes' (the default) or 'no' ('y', 'n', 'always', 'never'+     also work).  If you provide an argument you must use '=', e.g.+     '-pretty=yes'.++   When a reporting option appears more than once in the command line,+the last one takes precedence.++   Some reporting options can also be written as query arguments.+++File: hledger.info,  Node: Command options,  Next: Command arguments,  Prev: General options,  Up: OPTIONS++1.2 Command options+===================++To see options for a particular command, including command-specific+options, run: 'hledger COMMAND -h'.++   Command-specific options must be written after the command name, eg:+'hledger print -x'.++   Additionally, if the command is an add-on, you may need to put its+options after a double-hyphen, eg: 'hledger ui -- --watch'.  Or, you can+run the add-on executable directly: 'hledger-ui --watch'.+++File: hledger.info,  Node: Command arguments,  Next: Special characters,  Prev: Command options,  Up: OPTIONS++1.3 Command arguments+=====================++Most hledger commands accept arguments after the command name, which are+often a query, filtering the data in some way.++   You can save a set of command line options/arguments in a file, and+then reuse them by writing '@FILENAME' as a command line argument.  Eg:+'hledger bal @foo.args'.  (To prevent this, eg if you have an argument+that begins with a literal '@', precede it with '--', eg: 'hledger bal+-- @ARG').++   Inside the argument file, each line should contain just one option or+argument.  Avoid the use of spaces, except inside quotes (or you'll see+a confusing error).  Between a flag and its argument, use = (or+nothing).  Bad:++assets depth:2+-X USD++   Good:++assets+depth:2+-X=USD++   For special characters (see below), use one less level of quoting+than you would at the command prompt.  Bad:++-X"$"++   Good:++-X$++   See also: Save frequently used options.+++File: hledger.info,  Node: Special characters,  Next: Unicode characters,  Prev: Command arguments,  Up: OPTIONS++1.4 Special characters+======================++* Menu:++* Single escaping shell metacharacters::+* Double escaping regular expression metacharacters::+* Triple escaping for add-on commands::+* Less escaping::+++File: hledger.info,  Node: Single escaping shell metacharacters,  Next: Double escaping regular expression metacharacters,  Up: Special characters++1.4.1 Single escaping (shell metacharacters)+--------------------------------------------++In shell command lines, characters significant to your shell - such as+spaces, '<', '>', '(', ')', '|', '$' and '\' - should be "shell-escaped"+if you want hledger to see them.  This is done by enclosing them in+single or double quotes, or by writing a backslash before them.  Eg to+match an account name containing a space:++$ hledger register 'credit card'++   or:++$ hledger register credit\ card++   Windows users should keep in mind that 'cmd' treats single quote as a+regular character, so you should be using double quotes exclusively.+PowerShell treats both single and double quotes as quotes.+++File: hledger.info,  Node: Double escaping regular expression metacharacters,  Next: Triple escaping for add-on commands,  Prev: Single escaping shell metacharacters,  Up: Special characters++1.4.2 Double escaping (regular expression metacharacters)+---------------------------------------------------------++Characters significant in regular expressions (described below) - such+as '.', '^', '$', '[', ']', '(', ')', '|', and '\' - may need to be+"regex-escaped" if you don't want them to be interpreted by hledger's+regular expression engine.  This is done by writing backslashes before+them, but since backslash is typically also a shell metacharacter, both+shell-escaping and regex-escaping will be needed.  Eg to match a literal+'$' sign while using the bash shell:++$ hledger balance cur:'\$'++   or:++$ hledger balance cur:\\$+++File: hledger.info,  Node: Triple escaping for add-on commands,  Next: Less escaping,  Prev: Double escaping regular expression metacharacters,  Up: Special characters++1.4.3 Triple escaping (for add-on commands)+-------------------------------------------++When you use hledger to run an external add-on command (described+below), one level of shell-escaping is lost from any options or+arguments intended for by the add-on command, so those need an extra+level of shell-escaping.  Eg to match a literal '$' sign while using the+bash shell and running an add-on command ('ui'):++$ hledger ui cur:'\\$'++   or:++$ hledger ui cur:\\\\$++   If you wondered why _four_ backslashes, perhaps this helps:++unescaped:        '$'+escaped:          '\$'+double-escaped:   '\\$'+triple-escaped:   '\\\\$'++   Or, you can avoid the extra escaping by running the add-on executable+directly:++$ hledger-ui cur:\\$+++File: hledger.info,  Node: Less escaping,  Prev: Triple escaping for add-on commands,  Up: Special characters++1.4.4 Less escaping+-------------------++Options and arguments are sometimes used in places other than the shell+command line, where shell-escaping is not needed, so there you should+use one less level of escaping.  Those places include:++   * an @argumentfile+   * hledger-ui's filter field+   * hledger-web's search form+   * GHCI's prompt (used by developers).+++File: hledger.info,  Node: Unicode characters,  Next: Regular expressions,  Prev: Special characters,  Up: OPTIONS++1.5 Unicode characters+======================++hledger is expected to handle non-ascii characters correctly:++   * they should be parsed correctly in input files and on the command+     line, by all hledger tools (add, iadd, hledger-web's+     search/add/edit forms, etc.)++   * they should be displayed correctly by all hledger tools, and+     on-screen alignment should be preserved.++   This requires a well-configured environment.  Here are some tips:++   * A system locale must be configured, and it must be one that can+     decode the characters being used.  In bash, you can set a locale+     like this: 'export LANG=en_US.UTF-8'.  There are some more details+     in Troubleshooting.  This step is essential - without it, hledger+     will quit on encountering a non-ascii character (as with all+     GHC-compiled programs).++   * your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..)+     must support unicode++   * the terminal must be using a font which includes the required+     unicode glyphs++   * the terminal should be configured to display wide characters as+     double width (for report alignment)++   * on Windows, for best results you should run hledger in the same+     kind of environment in which it was built.  Eg hledger built in the+     standard CMD.EXE environment (like the binaries on our download+     page) might show display problems when run in a cygwin or msys+     terminal, and vice versa.  (See eg #961).+++File: hledger.info,  Node: Regular expressions,  Prev: Unicode characters,  Up: OPTIONS++1.6 Regular expressions+=======================++hledger uses regular expressions in a number of places:++   * query terms, on the command line and in the hledger-web search+     form: 'REGEX', 'desc:REGEX', 'cur:REGEX', 'tag:...=REGEX'+   * CSV rules conditional blocks: 'if REGEX ...'+   * account alias directives and options: 'alias /REGEX/ =+     REPLACEMENT', '--alias /REGEX/=REPLACEMENT'++   hledger's regular expressions come from the regex-tdfa library.  If+they're not doing what you expect, it's important to know exactly what+they support:++  1. they are case insensitive+  2. they are infix matching (they do not need to match the entire thing+     being matched)+  3. they are POSIX ERE (extended regular expressions)+  4. they also support GNU word boundaries ('\b', '\B', '\<', '\>')+  5. they do not support backreferences; if you write '\1', it will+     match the digit '1'.  Except when doing text replacement, eg in+     account aliases, where backreferences can be used in the+     replacement string to reference capturing groups in the search+     regexp.+  6. they do not support mode modifiers ('(?s)'), character classes+     ('\w', '\d'), or anything else not mentioned above.++   Some things to note:++   * In the 'alias' directive and '--alias' option, regular expressions+     must be enclosed in forward slashes ('/REGEX/').  Elsewhere in+     hledger, these are not required.++   * In queries, to match a regular expression metacharacter like '$' as+     a literal character, prepend a backslash.  Eg to search for amounts+     with the dollar sign in hledger-web, write 'cur:\$'.++   * On the command line, some metacharacters like '$' have a special+     meaning to the shell and so must be escaped at least once more.+     See Special characters.+++File: hledger.info,  Node: ENVIRONMENT,  Next: DATA FILES,  Prev: OPTIONS,  Up: Top++2 ENVIRONMENT+*************++*LEDGER_FILE* The journal file path when not specified with '-f'.++   On unix computers, the default value is: '~/.hledger.journal'.++   A more typical value is something like '~/finance/YYYY.journal',+where '~/finance' is a version-controlled finance directory and YYYY is+the current year.  Or, '~/finance/current.journal', where+current.journal is a symbolic link to YYYY.journal.++   The usual way to set this permanently is to add a command to one of+your shell's startup files (eg '~/.profile'):++export LEDGER_FILE=~/finance/current.journal`++   On some Mac computers, there is a more thorough way to set+environment variables, that will also affect applications started from+the GUI (eg, Emacs started from a dock icon): In+'~/.MacOSX/environment.plist', add an entry like:++{+  "LEDGER_FILE" : "~/finance/current.journal"+}++   For this to take effect you might need to 'killall Dock', or reboot.++   On Windows computers, the default value is probably+'C:\Users\MyUserName\.hledger.journal'.  You can change this by running+a command like this in a powershell window:++> setx LEDGER_FILE "C:\Users\MyUserName\finance\2021.journal"++   (Let us know if you need to be an Administrator, and if this persists+across a reboot.)++   *COLUMNS* The screen width used by the register command.  Default:+the full terminal width.++   *NO_COLOR* If this variable exists with any value, hledger will not+use ANSI color codes in terminal output.  This is overriden by the+-color/-colour option.+++File: hledger.info,  Node: DATA FILES,  Next: TIME PERIODS,  Prev: ENVIRONMENT,  Up: Top++3 DATA FILES+************++hledger reads transactions from one or more data files.  The default+data file is '$HOME/.hledger.journal' (or on Windows, something like+'C:/Users/USER/.hledger.journal').++   You can override this with the '$LEDGER_FILE' environment variable:++$ setenv LEDGER_FILE ~/finance/2016.journal+$ hledger stats++   or with one or more '-f/--file' options:++$ hledger -f /some/file -f another_file stats++   The file name '-' means standard input:++$ cat some.journal | hledger -f-++* Menu:++* Data formats::+* Multiple files::+* Strict mode::+++File: hledger.info,  Node: Data formats,  Next: Multiple files,  Up: DATA FILES++3.1 Data formats+================++Usually the data file is in hledger's journal format, but it can be in+any of the supported file formats, which currently are:++Reader:  Reads:                                   Used for file+                                                  extensions:+--------------------------------------------------------------------------+'journal'hledger journal files and some Ledger    '.journal' '.j'+         journals, for transactions               '.hledger' '.ledger'+'timeclock'timeclock files, for precise time      '.timeclock'+         logging+'timedot'timedot files, for approximate time      '.timedot'+         logging+'csv'    comma/semicolon/tab/other-separated      '.csv' '.ssv' '.tsv'+         values, for data import++   These formats are described in their own sections, below.++   hledger detects the format automatically based on the file extensions+shown above.  If it can't recognise the file extension, it assumes+'journal' format.  So for non-journal files, it's important to use a+recognised file extension, so as to either read successfully or to show+relevant error messages.++   You can also force a specific reader/format by prefixing the file+path with the format and a colon.  Eg, to read a .dat file as csv+format:++$ hledger -f csv:/some/csv-file.dat stats++   Or to read stdin ('-') as timeclock format:++$ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:-+++File: hledger.info,  Node: Multiple files,  Next: Strict mode,  Prev: Data formats,  Up: DATA FILES++3.2 Multiple files+==================++You can specify multiple '-f' options, to read multiple files as one big+journal.  There are some limitations with this:++   * most directives do not affect sibling files+   * balance assertions will not see any account balances from previous+     files++   If you need either of those things, you can++   * use a single parent file which includes the others+   * or concatenate the files into one before reading, eg: 'cat+     a.journal b.journal | hledger -f- CMD'.+++File: hledger.info,  Node: Strict mode,  Prev: Multiple files,  Up: DATA FILES++3.3 Strict mode+===============++hledger checks input files for valid data.  By default, the most+important errors are detected, while still accepting easy journal files+without a lot of declarations:++   * Are the input files parseable, with valid syntax ?+   * Are all transactions balanced ?+   * Do all balance assertions pass ?++   With the '-s'/'--strict' flag, additional checks are performed:++   * Are all accounts posted to, declared with an 'account' directive ?+     (Account error checking)+   * Are all commodities declared with a 'commodity' directive ?+     (Commodity error checking)+   * Are all commodity conversions declared explicitly ?++   You can use the check command to run individual checks - the ones+listed above and some more.+++File: hledger.info,  Node: TIME PERIODS,  Next: DEPTH,  Prev: DATA FILES,  Up: Top++4 TIME PERIODS+**************++* Menu:++* Smart dates::+* Report start & end date::+* Report intervals::+* Period expressions::+++File: hledger.info,  Node: Smart dates,  Next: Report start & end date,  Up: TIME PERIODS++4.1 Smart dates+===============++hledger's user interfaces accept a flexible "smart date" syntax.  Smart+dates allow some english words, can be relative to today's date, and can+have less-significant date parts omitted (defaulting to 1).++   Examples:++'2004/10/1',              exact date, several separators allowed.  Year+'2004-01-01',             is 4+ digits, month is 1-12, day is 1-31+'2004.9.1'+'2004'                    start of year+'2004/10'                 start of month+'10/1'                    month and day in current year+'21'                      day in current month+'october, oct'            start of month in current year+'yesterday, today,        -1, 0, 1 days from today+tomorrow'+'last/this/next           -1, 0, 1 periods from the current period+day/week/month/quarter/year'+'in n                     n periods from the current period+days/weeks/months/quarters/years'+'n                        n periods from the current period+days/weeks/months/quarters/years+ahead'+'n                        -n periods from the current period+days/weeks/months/quarters/years+ago'+'20181201'                8 digit YYYYMMDD with valid year month and+                          day+'201812'                  6 digit YYYYMM with valid year and month++   Counterexamples - malformed digit sequences might give surprising+results:++'201813'     6 digits with an invalid month is parsed as start of+             6-digit year+'20181301'   8 digits with an invalid month is parsed as start of+             8-digit year+'20181232'   8 digits with an invalid day gives an error+'201801012'  9+ digits beginning with a valid YYYYMMDD gives an error++   Note "today's date" can be overridden with the '--today' option, in+case it's needed for testing or for recreating old reports.  (Except for+periodic transaction rules; those are not affected by '--today'.)+++File: hledger.info,  Node: Report start & end date,  Next: Report intervals,  Prev: Smart dates,  Up: TIME PERIODS++4.2 Report start & end date+===========================++By default, most hledger reports will show the full span of time+represented by the journal data.  The report start date will be the+earliest transaction or posting date, and the report end date will be+the latest transaction, posting, or market price date.++   Often you will want to see a shorter time span, such as the current+month.  You can specify a start and/or end date using '-b/--begin',+'-e/--end', '-p/--period' or a 'date:' query (described below).  All of+these accept the smart date syntax.++   Some notes:++   * End dates are exclusive, as in Ledger, so you should write the date+     _after_ the last day you want to see in the report.+   * As noted in reporting options: among start/end dates specified with+     _options_, the last (i.e.  right-most) option takes precedence.+   * The effective report start and end dates are the intersection of+     the start/end dates from options and that from 'date:' queries.+     That is, 'date:2019-01 date:2019 -p'2000 to 2030'' yields January+     2019, the smallest common time span.+   * A report interval (see below) will adjust start/end dates, when+     needed, so that they fall on subperiod boundaries.++   Examples:++'-b           begin on St. Patrick's day 2016+2016/3/17'+'-e 12/1'     end at the start of december 1st of the current year+              (11/30 will be the last date included)+'-b           all transactions on or after the 1st of the current month+thismonth'+'-p           all transactions in the current month+thismonth'+'date:2016/3/17..'the above written as queries instead ('..' can also be+              replaced with '-')+'date:..12/1'+'date:thismonth..'+'date:thismonth'+++File: hledger.info,  Node: Report intervals,  Next: Period expressions,  Prev: Report start & end date,  Up: TIME PERIODS++4.3 Report intervals+====================++A report interval can be specified so that commands like register,+balance and activity become multi-period, showing each subperiod as a+separate row or column.++   The following "standard" report intervals can be enabled by using+their corresponding flag:++   * '-D/--daily'+   * '-W/--weekly'+   * '-M/--monthly'+   * '-Q/--quarterly'+   * '-Y/--yearly'++   These standard intervals always start on natural interval boundaries:+eg '--weekly' starts on mondays, '--monthly' starts on the first of the+month, '--yearly' always starts on January 1st, etc.++   Certain more complex intervals, and more flexible boundary dates, can+be specified by '-p/--period'.  These are described in period+expressions, below.++   Report intervals can only be specified by the flags above, and not by+query arguments, currently.++   Report intervals have another effect: multi-period reports are always+expanded to fill a whole number of subperiods.  So if you use a report+interval (other than '--daily'), and you have specified a start or end+date, you may notice those dates being overridden (ie, the report starts+earlier than your requested start date, or ends later than your+requested end date).  This is done to ensure "full" first and last+subperiods, so that all subperiods' numbers are comparable.++   To summarise:++   * In multiperiod reports, all subperiods are forced to be the same+     length, to simplify reporting.+   * Reports with the standard+     '--weekly'/'--monthly'/'--quarterly'/'--yearly' intervals are+     required to start on the first day of a week/month/quarter/year.+     We'd like more flexibility here but it isn't supported yet.+   * '--period' (below) can specify more complex intervals, starting on+     any date.+++File: hledger.info,  Node: Period expressions,  Prev: Report intervals,  Up: TIME PERIODS++4.4 Period expressions+======================++The '-p/--period' option accepts period expressions, a shorthand way of+expressing a start date, end date, and/or report interval all at once.++   Here's a basic period expression specifying the first quarter of+2009.  Note, hledger always treats start dates as inclusive and end+dates as exclusive:++'-p "from 2009/1/1 to 2009/4/1"'++   Keywords like "from" and "to" are optional, and so are the spaces, as+long as you don't run two dates together.  "to" can also be written as+".."  or "-".  These are equivalent to the above:++'-p "2009/1/1 2009/4/1"'+'-p2009/1/1to2009/4/1'+'-p2009/1/1..2009/4/1'++   Dates are smart dates, so if the current year is 2009, the above can+also be written as:++'-p "1/1 4/1"'+'-p "january-apr"'+'-p "this year to 4/1"'++   If you specify only one date, the missing start or end date will be+the earliest or latest transaction in your journal:++'-p "from 2009/1/1"'   everything after january 1, 2009+'-p "from 2009/1"'     the same+'-p "from 2009"'       the same+'-p "to 2009"'         everything before january 1, 2009++   A single date with no "from" or "to" defines both the start and end+date like so:++'-p "2009"'       the year 2009; equivalent to “2009/1/1 to 2010/1/1”+'-p "2009/1"'     the month of jan; equivalent to “2009/1/1 to 2009/2/1”+'-p "2009/1/1"'   just that day; equivalent to “2009/1/1 to 2009/1/2”++   Or you can specify a single quarter like so:++'-p "2009Q1"'   first quarter of 2009, equivalent to “2009/1/1 to 2009/4/1”+'-p "q4"'       fourth quarter of the current year++* Menu:++* Period expressions with a report interval::+* More complex report intervals::+* Intervals with custom start date::+* Periods or dates ?::+* Events on multiple weekdays::+++File: hledger.info,  Node: Period expressions with a report interval,  Next: More complex report intervals,  Up: Period expressions++4.4.1 Period expressions with a report interval+-----------------------------------------------++'-p/--period''s argument can also begin with, or entirely consist of, a+report interval.  This should be separated from the start/end dates (if+any) by a space, or the word 'in'.  The basic intervals (which can also+be written as command line flags) are 'daily', 'weekly', 'monthly',+'quarterly', and 'yearly'.  Some examples:++'-p "weekly from 2009/1/1 to 2009/4/1"'+'-p "monthly in 2008"'+'-p "quarterly"'++   As mentioned above, the 'weekly', 'monthly', 'quarterly' and 'yearly'+intervals require a report start date that is the first day of a week,+month, quarter or year.  And, report start/end dates will be expanded if+needed to span a whole number of intervals.++   For example:++'-p "weekly from           starts on 2008/12/29, closest preceding+2009/1/1 to 2009/4/1"'     Monday+'-p "monthly in            starts on 2018/11/01+2008/11/25"'+'-p "quarterly from        starts on 2009/04/01, ends on 2009/06/30,+2009-05-05 to              which are first and last days of Q2 2009+2009-06-01"'+'-p "yearly from           starts on 2009/01/01, first day of 2009+2009-12-29"'+++File: hledger.info,  Node: More complex report intervals,  Next: Intervals with custom start date,  Prev: Period expressions with a report interval,  Up: Period expressions++4.4.2 More complex report intervals+-----------------------------------++Some more complex kinds of interval are also supported in period+expressions:++   * 'biweekly'+   * 'fortnightly'+   * 'bimonthly'+   * 'every day|week|month|quarter|year'+   * 'every N days|weeks|months|quarters|years'++   These too will cause report start/end dates to be expanded, if+needed, to span a whole number of intervals.  Examples:++'-p "bimonthly from        periods will have boundaries on 2008/01/01,+2008"'                     2008/03/01, ...+'-p "every 2 weeks"'       starts on closest preceding Monday+'-p "every 5 month from    periods will have boundaries on 2009/03/01,+2009/03"'                  2009/08/01, ...+++File: hledger.info,  Node: Intervals with custom start date,  Next: Periods or dates ?,  Prev: More complex report intervals,  Up: Period expressions++4.4.3 Intervals with custom start date+--------------------------------------++All intervals mentioned above are required to start on their natural+calendar boundaries, but the following intervals can start on any date:++   Weekly on custom day:++   * 'every Nth day of week' ('th', 'nd', 'rd', or 'st' are all accepted+     after the number)+   * 'every WEEKDAYNAME' (full or three-letter english weekday name,+     case insensitive)++   Monthly on custom day:++   * 'every Nth day [of month]'+   * 'every Nth WEEKDAYNAME [of month]'++   Yearly on custom day:++   * 'every MM/DD [of year]' (month number and day of month number)+   * 'every MONTHNAME DDth [of year]' (full or three-letter english+     month name, case insensitive, and day of month number)+   * 'every DDth MONTHNAME [of year]' (equivalent to the above)++   Examples:++'-p "every 2nd day of    periods will go from Tue to Tue+week"'+'-p "every Tue"'         same+'-p "every 15th day"'    period boundaries will be on 15th of each+                         month+'-p "every 2nd           period boundaries will be on second Monday of+Monday"'                 each month+'-p "every 11/05"'       yearly periods with boundaries on 5th of+                         November+'-p "every 5th           same+November"'+'-p "every Nov 5th"'     same++   Show historical balances at end of the 15th day of each month (N is+an end date, exclusive as always):++$ hledger balance -H -p "every 16th day"++   Group postings from the start of wednesday to end of the following+tuesday (N is both (inclusive) start date and (exclusive) end date):++$ hledger register checking -p "every 3rd day of week"+++File: hledger.info,  Node: Periods or dates ?,  Next: Events on multiple weekdays,  Prev: Intervals with custom start date,  Up: Period expressions++4.4.4 Periods or dates ?+------------------------++Report intervals like the above are most often used with '-p|--period',+to divide reports into multiple subperiods - each generated date marks a+subperiod boundary.  Here, the periods between the dates are what's+important.++   But report intervals can also be used with '--forecast' to generate+future transactions, or with 'balance --budget' to generate budget+goal-setting transactions.  For these, the dates themselves are what+matters.+++File: hledger.info,  Node: Events on multiple weekdays,  Prev: Periods or dates ?,  Up: Period expressions++4.4.5 Events on multiple weekdays+---------------------------------++The 'every WEEKDAYNAME' form has a special variant with multiple day+names, comma-separated.  Eg: 'every mon,thu,sat'.  Also, 'weekday' and+'weekendday' are shorthand for 'mon,tue,wed,thu,fri' and 'sat,sun'+respectively.++   This form is mainly intended for use with '--forecast', to generate+periodic transactions on arbitrary days of the week.  It may be less+useful with '-p', since it divides each week into subperiods of unequal+length.  (Because gaps between periods are not allowed; if you'd like to+change this, see #1632.)++   Examples:++'-p "every         dates will be Mon, Wed, Fri; periods will be+mon,wed,fri"'      Mon-Tue, Wed-Thu, Fri-Sun+'-p "every         dates will be Mon, Tue, Wed, Thu, Fri; periods will+weekday"'          be Mon, Tue, Wed, Thu, Fri-Sun+'-p "every         dates will be Sat, Sun; periods will be Sat, Sun-Fri+weekendday"'+++File: hledger.info,  Node: DEPTH,  Next: QUERIES,  Prev: TIME PERIODS,  Up: Top++5 DEPTH+*******++With the '--depth NUM' option (short form: '-NUM'), commands like+account, balance and register will show only the uppermost accounts in+the account tree, down to level NUM. Use this when you want a summary+with less detail.  This flag has the same effect as a 'depth:' query+argument: 'depth:2', '--depth=2' or '-2' are equivalent.+++File: hledger.info,  Node: QUERIES,  Next: CONVERSION & COST,  Prev: DEPTH,  Up: Top++6 QUERIES+*********++One of hledger's strengths is being able to quickly report on a precise+subset of your data.  Most hledger commands accept optional query+arguments to restrict their scope.  The syntax is as follows:++   * Zero or more space-separated query terms.  These are most often+     account name substrings:++     'utilities food:groceries'++   * Terms with spaces or other special characters should be enclosed in+     quotes:++     '"personal care"'++   * Regular expressions are also supported:++     '"^expenses\b" "accounts (payable|receivable)"'++   * Add a query type prefix to match other parts of the data:++     'date:202012- desc:amazon cur:USD amt:">100" status:'++   * Add a 'not:' prefix to negate a term:++     'not:cur:USD'++* Menu:++* Query types::+* Combining query terms::+* Queries and command options::+* Queries and account aliases::+* Queries and valuation::+* Querying with account aliases::+* Querying with cost or value::+++File: hledger.info,  Node: Query types,  Next: Combining query terms,  Up: QUERIES++6.1 Query types+===============++Here are the types of query term available.  Remember these can also be+prefixed with *'not:'* to convert them into a negative match.++   *'acct:REGEX', 'REGEX'*+Match account names containing this (case insensitive) regular+expression.  This is the default query type when there is no prefix, and+regular expression syntax is typically not needed, so usually we just+write an account name substring, like 'expenses' or 'food'.++   *'amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N'*+Match postings with a single-commodity amount equal to, less than, or+greater than N. (Postings with multi-commodity amounts are not tested+and will always match.)  The comparison has two modes: if N is preceded+by a + or - sign (or is 0), the two signed numbers are compared.+Otherwise, the absolute magnitudes are compared, ignoring sign.++   *'code:REGEX'*+Match by transaction code (eg check number).++   *'cur:REGEX'*+Match postings or transactions including any amounts whose+currency/commodity symbol is fully matched by REGEX. (For a partial+match, use '.*REGEX.*').  Note, to match special characters which are+regex-significant, you need to escape them with '\'.  And for characters+which are significant to your shell you may need one more level of+escaping.  So eg to match the dollar sign:+'hledger print cur:\\$'.++   *'desc:REGEX'*+Match transaction descriptions.++   *'date:PERIODEXPR'*+Match dates (or with the '--date2' flag, secondary dates) within the+specified period.  PERIODEXPR is a period expression with no report+interval.  Examples:+'date:2016', 'date:thismonth', 'date:2/1-2/15',+'date:2021-07-27..nextquarter'.++   *'date2:PERIODEXPR'*+Match secondary dates within the specified period (independent of the+'--date2' flag).++   *'depth:N'*+Match (or display, depending on command) accounts at or above this+depth.++   *'note:REGEX'*+Match transaction notes (the part of the description right of '|', or+the whole description if there's no '|').++   *'payee:REGEX'*+Match transaction payee/payer names (the part of the description left of+'|', or the whole description if there's no '|').++   *'real:, real:0'*+Match real or virtual postings respectively.++   *'status:, status:!, status:*'*+Match unmarked, pending, or cleared transactions respectively.++   *'type:TYPECODES'*+Match by account type (see Declaring accounts > Account types).+'TYPECODES' is one or more of the single-letter account type codes+'ALERXCV', case insensitive.  Note 'type:A' and 'type:E' will also match+their respective subtypes 'C' (Cash) and 'V' (Conversion).  Certain+kinds of account alias can disrupt account types, see Rewriting accounts+> Aliases and account types.++   *'tag:REGEX[=REGEX]'*+Match by tag name, and optionally also by tag value.  (To match only by+value, use 'tag:.=REGEX'.)++   When querying by tag, note that:++   * Accounts also inherit the tags of their parent accounts+   * Postings also inherit the tags of their account and their+     transaction+   * Transactions also acquire the tags of their postings.++   (*'inacct:ACCTNAME'*+A special query term used automatically in hledger-web only: tells+hledger-web to show the transaction register for an account.)+++File: hledger.info,  Node: Combining query terms,  Next: Queries and command options,  Prev: Query types,  Up: QUERIES++6.2 Combining query terms+=========================++Most commands select things which match:++   * any of the description terms AND+   * any of the account terms AND+   * any of the status terms AND+   * all the other terms.++   while the print command shows transactions which:++   * match any of the description terms AND+   * have any postings matching any of the positive account terms AND+   * have no postings matching any of the negative account terms AND+   * match all the other terms.++   You can do more powerful queries (such as AND-ing two like terms) by+running a first query with 'print', and piping the result into a second+hledger command.  Eg: how much of food expenses was paid with cash ?++$ hledger print assets:cash | hledger -f- -I balance expenses:food++   If you are interested in full boolean expressions for queries, see+#203.+++File: hledger.info,  Node: Queries and command options,  Next: Queries and account aliases,  Prev: Combining query terms,  Up: QUERIES++6.3 Queries and command options+===============================++Some queries can also be expressed as command-line options: 'depth:2' is+equivalent to '--depth 2', 'date:2020' is equivalent to '-p 2020', etc.+When you mix command options and query arguments, generally the+resulting query is their intersection.+++File: hledger.info,  Node: Queries and account aliases,  Next: Queries and valuation,  Prev: Queries and command options,  Up: QUERIES++6.4 Queries and account aliases+===============================++When account names are rewritten with '--alias' or 'alias', 'acct:' will+match either the old or the new account name.+++File: hledger.info,  Node: Queries and valuation,  Next: Querying with account aliases,  Prev: Queries and account aliases,  Up: QUERIES++6.5 Queries and valuation+=========================++When amounts are converted to other commodities in cost or value+reports, 'cur:' and 'amt:' match the old commodity symbol and the old+amount quantity, not the new ones (except in hledger 1.22.0 where it's+reversed, see #1625).+++File: hledger.info,  Node: Querying with account aliases,  Next: Querying with cost or value,  Prev: Queries and valuation,  Up: QUERIES++6.6 Querying with account aliases+=================================++When account names are rewritten with '--alias' or 'alias', note that+'acct:' will match either the old or the new account name.+++File: hledger.info,  Node: Querying with cost or value,  Prev: Querying with account aliases,  Up: QUERIES++6.7 Querying with cost or value+===============================++When amounts are converted to other commodities in cost or value+reports, note that 'cur:' matches the new commodity symbol, and not the+old one, and 'amt:' matches the new quantity, and not the old one.+Note: this changed in hledger 1.22, previously it was the reverse, see+the discussion at #1625.+++File: hledger.info,  Node: CONVERSION & COST,  Next: VALUATION,  Prev: QUERIES,  Up: Top++7 CONVERSION & COST+*******************++This section is about converting between commodities.  Some definitions:++   * A "commodity conversion" is an exchange of one currency or+     commodity for another.  Eg a foreign currency exchange, or a+     purchase or sale of stock or cryptocurrency.++   * A "conversion transaction" is a transaction involving one or more+     such conversions.++   * "Conversion rate" is the exchange rate in a conversion - the cost+     per unit of one commodity in the other.++   * "Cost" is how much of one commodity was paid to acquire the other+     (when buying), or how much was received in exchange for the other+     (when selling).  We call both of these "cost" for convenience+     (after all, it is cost for one party or the other).++* Menu:++* Recording conversions::+* Inferring missing conversion rates::+* Inferring missing equity postings::+* Cost reporting::+* Conversion summary::+++File: hledger.info,  Node: Recording conversions,  Next: Inferring missing conversion rates,  Up: CONVERSION & COST++7.1 Recording conversions+=========================++As a concrete example, let's assume 100 EUR was converted to 120 USD.+There are several ways to record this in the journal, each with pros and+cons which will be explained in more detail below.  (Also, these+examples use journal format which is properly explained much further+below; sorry about that, you may want to read some of that first.)++* Menu:++* Implicit conversion::+* Priced conversion::+* Equity conversion::+* Priced equity conversion::+++File: hledger.info,  Node: Implicit conversion,  Next: Priced conversion,  Up: Recording conversions++7.1.1 Implicit conversion+-------------------------++You can just record the outflow (100 EUR) and inflow (120 USD) in the+appropriate asset account:++2021-01-01+    assets:cash    -100 EUR+    assets:cash     120 USD++   hledger will assume this transaction is balanced, inferring that the+conversion rate must be 1 EUR = 1.20 USD. You can see the inferred rate+by using 'hledger print -x'.++   Pro:++   * Easy, concise+   * hledger can do cost reporting++   Con:++   * Less error checking - typos in amounts or commodity symbols may not+     be detected+   * conversion rate is not clear+   * disturbs the accounting equation++   You can prevent accidental implicit conversions due to a mistyped+commodity symbol, by using 'hledger check commodities'.  You can prevent+implicit conversions entirely, by using 'hledger check+balancednoautoconversion', or '-s/--strict'.+++File: hledger.info,  Node: Priced conversion,  Next: Equity conversion,  Prev: Implicit conversion,  Up: Recording conversions++7.1.2 Priced conversion+-----------------------++You can add the conversion rate using @ notation:++2021-01-01+    assets:cash        -100 EUR @ 1.20 USD+    assets:cash         120 USD++   Now hledger will check that 100 * 1.20 = 120, and would report an+error otherwise.++   Pro:++   * Still concise+   * makes the conversion rate clear+   * provides some error checking+   * hledger can do cost reporting++   Con:++   * Disturbs the accounting equation+++File: hledger.info,  Node: Equity conversion,  Next: Priced equity conversion,  Prev: Priced conversion,  Up: Recording conversions++7.1.3 Equity conversion+-----------------------++In strict double entry bookkeeping, the above transaction is not+balanced in EUR or in USD, since some EUR disappears, and some USD+appears.  This violates the accounting equation (A+L+E=0), and prevents+reports like 'balancesheetequity' from showing a zero total.++   The proper way to make it balance is to add a balancing posting for+each commodity, using an equity account:++2021-01-01+    assets:cash        -100 EUR+    equity:conversion   100 EUR+    equity:conversion  -120 USD+    assets:cash         120 USD++   Pro:++   * Preserves the accounting equation+   * keeps track of conversions and related gains/losses in one place+   * works in any double entry accounting system++   Con:++   * More verbose+   * conversion rate is not clear+   * hledger can not do cost reporting+++File: hledger.info,  Node: Priced equity conversion,  Prev: Equity conversion,  Up: Recording conversions++7.1.4 Priced equity conversion+------------------------------++Another possible notation would be to record both the conversion rate+and the equity postings:++2021-01-01+    assets:cash        -100 EUR @ 1.20 USD+    equity:conversion   100 EUR+    equity:conversion  -120 USD+    assets:cash         120 USD++   hledger currently does not allow this; instead, you can record the+conversion rate as a comment.+++File: hledger.info,  Node: Inferring missing conversion rates,  Next: Inferring missing equity postings,  Prev: Recording conversions,  Up: CONVERSION & COST++7.2 Inferring missing conversion rates+======================================++hledger will do this automatically for implicit conversions.  Currently+it can not do this for equity conversions.+++File: hledger.info,  Node: Inferring missing equity postings,  Next: Cost reporting,  Prev: Inferring missing conversion rates,  Up: CONVERSION & COST++7.3 Inferring missing equity postings+=====================================++With the '--infer-equity' flag, hledger will add equity postings to+priced and implicit conversions (and move the conversion rate into a+comment).+++File: hledger.info,  Node: Cost reporting,  Next: Conversion summary,  Prev: Inferring missing equity postings,  Up: CONVERSION & COST++7.4 Cost reporting+==================++With the '-B/--cost' flag, hledger will convert the amounts in priced+and implicit conversions to their cost in the other commodity.  This is+useful to see a report of what you paid for things (or how much you sold+things for).  Currently '-B/--cost' does not work on equity conversions,+and it disables '--infer-equity'.++   These operations are transient, only affecting reports.  If you want+to change the journal file permanently, you could pipe each entry+through 'hledger -f- -I print [-x] [--infer-equity] [-B]'+++File: hledger.info,  Node: Conversion summary,  Prev: Cost reporting,  Up: CONVERSION & COST++7.5 Conversion summary+======================++   * Recording the conversion rate is good because it makes that clear+     and allows cost reporting.+   * Recording equity postings is good because it balances the+     accounting equation and is correct bookkeeping.+   * Combining these is not yet supported, so you have to choose.  For+     now, priced conversions are a good compromise, so that:+        * When you want to see the cost (or sale proceeds) of things,+          use '-B/--cost'.+        * When you want to see a balanced balance sheet or correct+          journal entries, use '--infer-equity'.+        * Combining these is not yet supported; '-B/--cost' will take+          precedence.++   * Conversion/cost operations are performed before valuation.+++File: hledger.info,  Node: VALUATION,  Next: PIVOTING,  Prev: CONVERSION & COST,  Up: Top++8 VALUATION+***********++Instead of reporting amounts in their original commodity, hledger can+convert them to cost/sale amount (using the conversion rate recorded in+the transaction), and/or to market value (using some market price on a+certain date).  This is controlled by the '--value=TYPE[,COMMODITY]'+option, which will be described below.  We also provide the simpler '-V'+and '-X COMMODITY' options, and often one of these is all you need:++* Menu:++* -V Value::+* -X Value in specified commodity::+* Valuation date::+* Market prices::+* --infer-market-prices market prices from transactions::+* Valuation commodity::+* Simple valuation examples::+* --value Flexible valuation::+* More valuation examples::+* Interaction of valuation and queries::+* Effect of valuation on reports::+++File: hledger.info,  Node: -V Value,  Next: -X Value in specified commodity,  Up: VALUATION++8.1 -V: Value+=============++The '-V/--market' flag converts amounts to market value in their default+_valuation commodity_, using the market prices in effect on the+_valuation date(s)_, if any.  More on these in a minute.+++File: hledger.info,  Node: -X Value in specified commodity,  Next: Valuation date,  Prev: -V Value,  Up: VALUATION++8.2 -X: Value in specified commodity+====================================++The '-X/--exchange=COMM' option is like '-V', except you tell it which+currency you want to convert to, and it tries to convert everything to+that.+++File: hledger.info,  Node: Valuation date,  Next: Market prices,  Prev: -X Value in specified commodity,  Up: VALUATION++8.3 Valuation date+==================++Since market prices can change from day to day, market value reports+have a valuation date (or more than one), which determines which market+prices will be used.++   For single period reports, if an explicit report end date is+specified, that will be used as the valuation date; otherwise the+valuation date is the journal's end date.++   For multiperiod reports, each column/period is valued on the last day+of the period, by default.+++File: hledger.info,  Node: Market prices,  Next: --infer-market-prices market prices from transactions,  Prev: Valuation date,  Up: VALUATION++8.4 Market prices+=================++To convert a commodity A to its market value in another commodity B,+hledger looks for a suitable market price (exchange rate) as follows, in+this order of preference :++  1. A _declared market price_ or _inferred market price_: A's latest+     market price in B on or before the valuation date as declared by a+     P directive, or (with the '--infer-market-prices' flag) inferred+     from transaction prices.++  2. A _reverse market price_: the inverse of a declared or inferred+     market price from B to A.++  3. A _forward chain of market prices_: a synthetic price formed by+     combining the shortest chain of "forward" (only 1 above) market+     prices, leading from A to B.++  4. _Any chain of market prices_: a chain of any market prices,+     including both forward and reverse prices (1 and 2 above), leading+     from A to B.++   There is a limit to the length of these price chains; if hledger+reaches that length without finding a complete chain or exhausting all+possibilities, it will give up (with a "gave up" message visible in+'--debug=2' output).  That limit is currently 1000.++   Amounts for which no suitable market price can be found, are not+converted.+++File: hledger.info,  Node: --infer-market-prices market prices from transactions,  Next: Valuation commodity,  Prev: Market prices,  Up: VALUATION++8.5 -infer-market-prices: market prices from transactions+=========================================================++Normally, market value in hledger is fully controlled by, and requires,+P directives in your journal.  Since adding and updating those can be a+chore, and since transactions usually take place at close to market+value, why not use the recorded transaction prices as additional market+prices (as Ledger does) ?  We could produce value reports without+needing P directives at all.++   Adding the '--infer-market-prices' flag to '-V', '-X' or '--value'+enables this.  So for example, 'hledger bs -V --infer-market-prices'+will get market prices both from P directives and from transactions.+(And if both occur on the same day, the P directive takes precedence).++   There is a downside: value reports can sometimes be affected in+confusing/undesired ways by your journal entries.  If this happens to+you, read all of this Valuation section carefully, and try adding+'--debug' or '--debug=2' to troubleshoot.++   '--infer-market-prices' can infer market prices from:++   * multicommodity transactions with explicit prices ('@'/'@@')++   * multicommodity transactions with implicit prices (no '@', two+     commodities, unbalanced).  (With these, the order of postings+     matters.  'hledger print -x' can be useful for troubleshooting.)++   * but not, currently, from "more correct" multicommodity transactions+     (no '@', multiple commodities, balanced).+++File: hledger.info,  Node: Valuation commodity,  Next: Simple valuation examples,  Prev: --infer-market-prices market prices from transactions,  Up: VALUATION++8.6 Valuation commodity+=======================++*When you specify a valuation commodity ('-X COMM' or '--value+TYPE,COMM'):*+hledger will convert all amounts to COMM, wherever it can find a+suitable market price (including by reversing or chaining prices).++   *When you leave the valuation commodity unspecified ('-V' or '--value+TYPE'):*+For each commodity A, hledger picks a default valuation commodity as+follows, in this order of preference:++  1. The price commodity from the latest P-declared market price for A+     on or before valuation date.++  2. The price commodity from the latest P-declared market price for A+     on any date.  (Allows conversion to proceed when there are inferred+     prices before the valuation date.)++  3. If there are no P directives at all (any commodity or date) and the+     '--infer-market-prices' flag is used: the price commodity from the+     latest transaction-inferred price for A on or before valuation+     date.++   This means:++   * If you have P directives, they determine which commodities '-V'+     will convert, and to what.++   * If you have no P directives, and use the '--infer-market-prices'+     flag, transaction prices determine it.++   Amounts for which no valuation commodity can be found are not+converted.+++File: hledger.info,  Node: Simple valuation examples,  Next: --value Flexible valuation,  Prev: Valuation commodity,  Up: VALUATION++8.7 Simple valuation examples+=============================++Here are some quick examples of '-V':++; one euro is worth this many dollars from nov 1+P 2016/11/01 € $1.10++; purchase some euros on nov 3+2016/11/3+    assets:euros        €100+    assets:checking++; the euro is worth fewer dollars by dec 21+P 2016/12/21 € $1.03++   How many euros do I have ?++$ hledger -f t.j bal -N euros+                €100  assets:euros++   What are they worth at end of nov 3 ?++$ hledger -f t.j bal -N euros -V -e 2016/11/4+             $110.00  assets:euros++   What are they worth after 2016/12/21 ?  (no report end date+specified, defaults to today)++$ hledger -f t.j bal -N euros -V+             $103.00  assets:euros+++File: hledger.info,  Node: --value Flexible valuation,  Next: More valuation examples,  Prev: Simple valuation examples,  Up: VALUATION++8.8 -value: Flexible valuation+==============================++'-V' and '-X' are special cases of the more general '--value' option:++ --value=TYPE[,COMM]  TYPE is then, end, now or YYYY-MM-DD.+                      COMM is an optional commodity symbol.+                      Shows amounts converted to:+                      - default valuation commodity (or COMM) using market prices at posting dates+                      - default valuation commodity (or COMM) using market prices at period end(s)+                      - default valuation commodity (or COMM) using current market prices+                      - default valuation commodity (or COMM) using market prices at some date++   The TYPE part selects cost or value and valuation date:++'--value=then'++     Convert amounts to their value in the default valuation commodity,+     using market prices on each posting's date.+'--value=end'++     Convert amounts to their value in the default valuation commodity,+     using market prices on the last day of the report period (or if+     unspecified, the journal's end date); or in multiperiod reports,+     market prices on the last day of each subperiod.+'--value=now'++     Convert amounts to their value in the default valuation commodity+     using current market prices (as of when report is generated).+'--value=YYYY-MM-DD'++     Convert amounts to their value in the default valuation commodity+     using market prices on this date.++   To select a different valuation commodity, add the optional ',COMM'+part: a comma, then the target commodity's symbol.  Eg:+*'--value=now,EUR'*.  hledger will do its best to convert amounts to+this commodity, deducing market prices as described above.+++File: hledger.info,  Node: More valuation examples,  Next: Interaction of valuation and queries,  Prev: --value Flexible valuation,  Up: VALUATION++8.9 More valuation examples+===========================++Here are some examples showing the effect of '--value', as seen with+'print':++P 2000-01-01 A  1 B+P 2000-02-01 A  2 B+P 2000-03-01 A  3 B+P 2000-04-01 A  4 B++2000-01-01+  (a)      1 A @ 5 B++2000-02-01+  (a)      1 A @ 6 B++2000-03-01+  (a)      1 A @ 7 B++   Show the cost of each posting:++$ hledger -f- print --cost+2000-01-01+    (a)             5 B++2000-02-01+    (a)             6 B++2000-03-01+    (a)             7 B++   Show the value as of the last day of the report period (2000-02-29):++$ hledger -f- print --value=end date:2000/01-2000/03+2000-01-01+    (a)             2 B++2000-02-01+    (a)             2 B++   With no report period specified, that shows the value as of the last+day of the journal (2000-03-01):++$ hledger -f- print --value=end+2000-01-01+    (a)             3 B++2000-02-01+    (a)             3 B++2000-03-01+    (a)             3 B++   Show the current value (the 2000-04-01 price is still in effect+today):++$ hledger -f- print --value=now+2000-01-01+    (a)             4 B++2000-02-01+    (a)             4 B++2000-03-01+    (a)             4 B++   Show the value on 2000/01/15:++$ hledger -f- print --value=2000-01-15+2000-01-01+    (a)             1 B++2000-02-01+    (a)             1 B++2000-03-01+    (a)             1 B++   You may need to explicitly set a commodity's display style, when+reverse prices are used.  Eg this output might be surprising:++P 2000-01-01 A 2B++2000-01-01+  a  1B+  b++$ hledger print -x -X A+2000-01-01+    a               0+    b               0++   Explanation: because there's no amount or commodity directive+specifying a display style for A, 0.5A gets the default style, which+shows no decimal digits.  Because the displayed amount looks like zero,+the commodity symbol and minus sign are not displayed either.  Adding a+commodity directive sets a more useful display style for A:++P 2000-01-01 A 2B+commodity 0.00A++2000-01-01+  a  1B+  b++$ hledger print -X A+2000-01-01+    a           0.50A+    b          -0.50A+++File: hledger.info,  Node: Interaction of valuation and queries,  Next: Effect of valuation on reports,  Prev: More valuation examples,  Up: VALUATION++8.10 Interaction of valuation and queries+=========================================++When matching postings based on queries in the presence of valuation,+the following happens.++  1. The query is separated into two parts:+       1. the currency ('cur:') or amount ('amt:').+       2. all other parts.++  2. The postings are matched to the currency and amount queries based+     on pre-valued amounts.+  3. Valuation is applied to the postings.+  4. The postings are matched to the other parts of the query based on+     post-valued amounts.++   See: 1625+++File: hledger.info,  Node: Effect of valuation on reports,  Prev: Interaction of valuation and queries,  Up: VALUATION++8.11 Effect of valuation on reports+===================================++Here is a reference for how valuation is supposed to affect each part of+hledger's reports (and a glossary).  (It's wide, you'll have to scroll+sideways.)  It may be useful when troubleshooting.  If you find+problems, please report them, ideally with a reproducible example.+Related: #329, #1083.++Report     '-B',        '-V', '-X'   '--value=then'     '--value=end''--value=DATE',+type       '--cost'                                                  '--value=now'+------------------------------------------------------------------------------+*print*+posting    cost         value at     value at posting   value at     value+amounts                 report end   date               report or    at+                        or today                        journal      DATE/today+                                                        end+balance    unchanged    unchanged    unchanged          unchanged    unchanged+assertions/assignments+*register*+starting   cost         value at     valued at day      value at     value+balance                 report or    each historical    report or    at+(-H)                    journal      posting was made   journal      DATE/today+                        end                             end+starting   cost         value at     valued at day      value at     value+balance                 day before   each historical    day before   at+(-H)                    report or    posting was made   report or    DATE/today+with                    journal                         journal+report                  start                           start+interval+posting    cost         value at     value at posting   value at     value+amounts                 report or    date               report or    at+                        journal                         journal      DATE/today+                        end                             end+summary    summarised   value at     sum of postings    value at     value+posting    cost         period       in interval,       period       at+amounts                 ends         valued at          ends         DATE/today+with                                 interval start+report+interval+running    sum/average  sum/average  sum/average of     sum/average  sum/average+total/averageof         of           displayed values   of           of+           displayed    displayed                       displayed    displayed+           values       values                          values       values+*balance+(bs,+bse, cf,+is)*+balance    sums of      value at     value at posting   value at     value+changes    costs        report end   date               report or    at+                        or today                        journal      DATE/today+                        of sums of                      end of       of+                        postings                        sums of      sums+                                                        postings     of+                                                                     postings+budget     like         like         like balance       like         like+amounts    balance      balance      changes            balances     balance+(-budget)  changes      changes                                      changes+grand      sum of       sum of       sum of displayed   sum of       sum of+total      displayed    displayed    valued             displayed    displayed+           values       values                          values       values+*balance+(bs,+bse, cf,+is) with+report+interval*+starting   sums of      value at     sums of values     value at     sums+balances   costs of     report       of postings        report       of+(-H)       postings     start of     before report      start of     postings+           before       sums of      start at           sums of      before+           report       all          respective         all          report+           start        postings     posting dates      postings     start+                        before                          before+                        report                          report+                        start                           start+balance    sums of      same as      sums of values     balance      value+changes    costs of     -value=end   of postings in     change in    at+(bal,      postings                  period at          each         DATE/today+is, bs     in period                 respective         period,      of+-change,                             posting dates      valued at    sums+cf                                                      period       of+-change)                                                ends         postings+end        sums of      same as      sums of values     period end   value+balances   costs of     -value=end   of postings from   balances,    at+(bal -H,   postings                  before period      valued at    DATE/today+is -H,     from                      start to period    period       of+bs, cf)    before                    end at             ends         sums+           report                    respective                      of+           start to                  posting dates                   postings+           period end+budget     like         like         like balance       like         like+amounts    balance      balance      changes/end        balances     balance+(-budget)  changes/end  changes/end  balances                        changes/end+           balances     balances                                     balances+row        sums,        sums,        sums, averages     sums,        sums,+totals,    averages     averages     of displayed       averages     averages+row        of           of           values             of           of+averages   displayed    displayed                       displayed    displayed+(-T, -A)   values       values                          values       values+column     sums of      sums of      sums of            sums of      sums+totals     displayed    displayed    displayed values   displayed    of+           values       values                          values       displayed+                                                                     values+grand      sum,         sum,         sum, average of    sum,         sum,+total,     average of   average of   column totals      average of   average+grand      column       column                          column       of+average    totals       totals                          totals       column+                                                                     totals++   '--cumulative' is omitted to save space, it works like '-H' but with+a zero starting balance.++   *Glossary:*++_cost_++     calculated using price(s) recorded in the transaction(s).+_value_++     market value using available market price declarations, or the+     unchanged amount if no conversion rate can be found.+_report start_++     the first day of the report period specified with -b or -p or+     date:, otherwise today.+_report or journal start_++     the first day of the report period specified with -b or -p or+     date:, otherwise the earliest transaction date in the journal,+     otherwise today.+_report end_++     the last day of the report period specified with -e or -p or date:,+     otherwise today.+_report or journal end_++     the last day of the report period specified with -e or -p or date:,+     otherwise the latest transaction date in the journal, otherwise+     today.+_report interval_++     a flag (-D/-W/-M/-Q/-Y) or period expression that activates the+     report's multi-period mode (whether showing one or many+     subperiods).+++File: hledger.info,  Node: PIVOTING,  Next: OUTPUT,  Prev: VALUATION,  Up: Top++9 PIVOTING+**********++Normally hledger sums amounts, and organizes them in a hierarchy, based+on account name.  The '--pivot FIELD' option causes it to sum and+organize hierarchy based on the value of some other field instead.+FIELD can be: 'code', 'description', 'payee', 'note', or the full name+(case insensitive) of any tag.  As with account names, values containing+'colon:separated:parts' will be displayed hierarchically in reports.++   '--pivot' is a general option affecting all reports; you can think of+hledger transforming the journal before any other processing, replacing+every posting's account name with the value of the specified field on+that posting, inheriting it from the transaction or using a blank value+if it's not present.++   An example:++2016/02/16 Member Fee Payment+    assets:bank account                    2 EUR+    income:member fees                    -2 EUR  ; member: John Doe++   Normal balance report showing account names:++$ hledger balance+               2 EUR  assets:bank account+              -2 EUR  income:member fees+--------------------+                   0++   Pivoted balance report, using member: tag values instead:++$ hledger balance --pivot member+               2 EUR+              -2 EUR  John Doe+--------------------+                   0++   One way to show only amounts with a member: value (using a query,+described below):++$ hledger balance --pivot member tag:member=.+              -2 EUR  John Doe+--------------------+              -2 EUR++   Another way (the acct: query matches against the pivoted "account+name"):++$ hledger balance --pivot member acct:.+              -2 EUR  John Doe+--------------------+              -2 EUR+++File: hledger.info,  Node: OUTPUT,  Next: COMMANDS,  Prev: PIVOTING,  Up: Top++10 OUTPUT+*********++* Menu:++* Output destination::+* Output styling::+* Output format::+* Commodity styles::+++File: hledger.info,  Node: Output destination,  Next: Output styling,  Up: OUTPUT++10.1 Output destination+=======================++hledger commands send their output to the terminal by default.  You can+of course redirect this, eg into a file, using standard shell syntax:++$ hledger print > foo.txt++   Some commands (print, register, stats, the balance commands) also+provide the '-o/--output-file' option, which does the same thing without+needing the shell.  Eg:++$ hledger print -o foo.txt+$ hledger print -o -        # write to stdout (the default)++   hledger can optionally produce debug output (if enabled with+'--debug=N'); this goes to stderr, and is not affected by+'-o/--output-file'.  If you need to capture it, use shell redirects, eg:+'hledger bal --debug=3 >file 2>&1'.+++File: hledger.info,  Node: Output styling,  Next: Output format,  Prev: Output destination,  Up: OUTPUT++10.2 Output styling+===================++hledger commands can produce colour output when the terminal supports+it.  This is controlled by the '--color/--colour' option: - if the+'--color/--colour' option is given a value of 'yes' or 'always' (or 'no'+or 'never'), colour will (or will not) be used; - otherwise, if the+'NO_COLOR' environment variable is set, colour will not be used; -+otherwise, colour will be used if the output (terminal or file) supports+it.++   hledger commands can also use unicode box-drawing characters to+produce prettier tables and output.  This is controlled by the+'--pretty' option: - if the '--pretty' option is given a value of 'yes'+or 'always' (or 'no' or 'never'), unicode characters will (or will not)+be used; - otherwise, unicode characters will not be used.+++File: hledger.info,  Node: Output format,  Next: Commodity styles,  Prev: Output styling,  Up: OUTPUT++10.3 Output format+==================++Some commands offer additional output formats, other than the usual+plain text terminal output.  Here are those commands and the formats+currently supported:++-                    txt     csv     html      json   sql+------------------------------------------------------------+aregister            Y       Y                 Y+balance              Y _1_   Y _1_   Y _1,2_   Y+balancesheet         Y _1_   Y _1_   Y _1_     Y+balancesheetequity   Y _1_   Y _1_   Y _1_     Y+cashflow             Y _1_   Y _1_   Y _1_     Y+incomestatement      Y _1_   Y _1_   Y _1_     Y+print                Y       Y                 Y      Y+register             Y       Y                 Y++   * _1 Also affected by the balance commands' '--layout' option._+   * _2 'balance' does not support html output without a report interval+     or with '--budget'._++   The output format is selected by the '-O/--output-format=FMT' option:++$ hledger print -O csv    # print CSV on stdout++   or by the filename extension of an output file specified with the+'-o/--output-file=FILE.FMT' option:++$ hledger balancesheet -o foo.csv    # write CSV to foo.csv++   The '-O' option can be combined with '-o' to override the file+extension, if needed:++$ hledger balancesheet -o foo.txt -O csv    # write CSV to foo.txt++* Menu:++* CSV output::+* HTML output::+* JSON output::+* SQL output::+++File: hledger.info,  Node: CSV output,  Next: HTML output,  Up: Output format++10.3.1 CSV output+-----------------++   * In CSV output, digit group marks (such as thousands separators) are+     disabled automatically.+++File: hledger.info,  Node: HTML output,  Next: JSON output,  Prev: CSV output,  Up: Output format++10.3.2 HTML output+------------------++   * HTML output can be styled by an optional 'hledger.css' file in the+     same directory.+++File: hledger.info,  Node: JSON output,  Next: SQL output,  Prev: HTML output,  Up: Output format++10.3.3 JSON output+------------------++   * Not yet much used; real-world feedback is welcome.++   * Our JSON is rather large and verbose, as it is quite a faithful+     representation of hledger's internal data types.  To understand the+     JSON, read the Haskell type definitions, which are mostly in+     https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs.++   * hledger represents quantities as Decimal values storing up to 255+     significant digits, eg for repeating decimals.  Such numbers can+     arise in practice (from automatically-calculated transaction+     prices), and would break most JSON consumers.  So in JSON, we show+     quantities as simple Numbers with at most 10 decimal places.  We+     don't limit the number of integer digits, but that part is under+     your control.  We hope this approach will not cause problems in+     practice; if you find otherwise, please let us know.  (Cf #1195)+++File: hledger.info,  Node: SQL output,  Prev: JSON output,  Up: Output format++10.3.4 SQL output+-----------------++   * Not yet much used; real-world feedback is welcome.++   * SQL output is expected to work with sqlite, MySQL and PostgreSQL++   * SQL output is structured with the expectations that statements will+     be executed in the empty database.  If you already have tables+     created via SQL output of hledger, you would probably want to+     either clear tables of existing data (via 'delete' or 'truncate'+     SQL statements) or drop tables completely as otherwise your+     postings will be duped.+++File: hledger.info,  Node: Commodity styles,  Prev: Output format,  Up: OUTPUT++10.4 Commodity styles+=====================++The display style of a commodity/currency is inferred according to the+rules described in Commodity display style.  The inferred display style+can be overridden by an optional '-c/--commodity-style' option+(Exceptions: as is the case for inferred styles, price amounts, and all+amounts displayed by the 'print' command, will be displayed with all of+their decimal digits visible, regardless of the specified precision).+For example, the following will override the display style for dollars.++$ hledger print -c '$1.000,0'++   The format specification of the style is identical to the commodity+display style specification for the commodity directive.  The command+line option can be supplied repeatedly to override the display style for+multiple commodity/currency symbols.+++File: hledger.info,  Node: COMMANDS,  Next: JOURNAL FORMAT,  Prev: OUTPUT,  Up: Top++11 COMMANDS+***********++hledger provides a number of commands for producing reports and managing+your data.  Run 'hledger' with no arguments to list the commands+available, and 'hledger CMD' to run a command.  CMD can be the full+command name, or its standard abbreviation shown in the commands list,+or any unambiguous prefix of the name.  Eg: 'hledger bal'.++   Here are the built-in commands, with the most often-used in bold:++   *Data entry:*++   These data entry commands are the only ones which can modify your+journal file.++   * *add* - add transactions using guided prompts+   * *import* - add any new transactions from other files (eg csv)++   *Data management:*++   * check - check for various kinds of issue in the data+   * close (equity) - generate balance-resetting transactions+   * diff - compare account transactions in two journal files+   * rewrite - generate extra postings, similar to print -auto++   *Financial statements:*++   * *aregister (areg)* - show transactions in a particular account+   * *balancesheet (bs)* - show assets, liabilities and net worth+   * balancesheetequity (bse) - show assets, liabilities and equity+   * cashflow (cf) - show changes in liquid assets+   * *incomestatement (is)* - show revenues and expenses+   * roi - show return on investments++   *Miscellaneous reports:*++   * accounts - show account names+   * activity - show postings-per-interval bar charts+   * *balance (bal)* - show balance changes/end balances/budgets in any+     accounts+   * codes - show transaction codes+   * commodities - show commodity/currency symbols+   * descriptions - show unique transaction descriptions+   * files - show input file paths+   * help - show hledger user manuals in several formats+   * notes - show unique note segments of transaction descriptions+   * payees - show unique payee segments of transaction descriptions+   * prices - show market price records+   * *print* - show transactions (journal entries)+   * print-unique - show only transactions with unique descriptions+   * *register (reg)* - show postings in one or more accounts & running+     total+   * register-match - show a recent posting that best matches a+     description+   * stats - show journal statistics+   * tags - show tag names+   * test - run self tests++   *Add-on commands:*++   Programs or scripts named 'hledger-SOMETHING' in your PATH are add-on+commands; these appear in the commands list with a '+' mark.  Two of+these are maintained and released with hledger:++   * *ui* - an efficient terminal interface (TUI) for hledger+   * *web* - a simple web interface (WUI) for hledger++   And these add-ons are maintained separately:++   * iadd - a more interactive alternative for the add command+   * interest - generates interest transactions according to various+     schemes+   * stockquotes - downloads market prices for your commodities from+     AlphaVantage _(experimental)_++   Next, the detailed command docs, in alphabetical order.++* Menu:++* accounts::+* activity::+* add::+* aregister::+* balance::+* balancesheet::+* balancesheetequity::+* cashflow::+* check::+* close::+* codes::+* commodities::+* descriptions::+* diff::+* files::+* help::+* import::+* incomestatement::+* notes::+* payees::+* prices::+* print::+* print-unique::+* register::+* register-match::+* rewrite::+* roi::+* stats::+* tags::+* test::+* About add-on commands::+++File: hledger.info,  Node: accounts,  Next: activity,  Up: COMMANDS++11.1 accounts+=============++accounts+Show account names.++   This command lists account names, either declared with account+directives (-declared), posted to (-used), or both (the default).  With+query arguments, only matched account names and account names referenced+by matched postings are shown.  It shows a flat list by default.  With+'--tree', it uses indentation to show the account hierarchy.  In flat+mode you can add '--drop N' to omit the first few account name+components.  Account names can be depth-clipped with 'depth:N' or+'--depth N' or '-N'.++   With '--types', it also shows each account's type, if it's known.+(See Declaring accounts > Account types.)++   Examples:++$ hledger accounts+assets:bank:checking+assets:bank:saving+assets:cash+expenses:food+expenses:supplies+income:gifts+income:salary+liabilities:debts+++File: hledger.info,  Node: activity,  Next: add,  Prev: accounts,  Up: COMMANDS++11.2 activity+=============++activity+Show an ascii barchart of posting counts per interval.++   The activity command displays an ascii histogram showing transaction+counts by day, week, month or other reporting interval (by day is the+default).  With query arguments, it counts only matched transactions.++   Examples:++$ hledger activity --quarterly+2008-01-01 **+2008-04-01 *******+2008-07-01 +2008-10-01 **+++File: hledger.info,  Node: add,  Next: aregister,  Prev: activity,  Up: COMMANDS++11.3 add+========++add+Prompt for transactions and add them to the journal.  Any arguments will+be used as default inputs for the first N prompts.++   Many hledger users edit their journals directly with a text editor,+or generate them from CSV. For more interactive data entry, there is the+'add' command, which prompts interactively on the console for new+transactions, and appends them to the journal file (if there are+multiple '-f FILE' options, the first file is used.)  Existing+transactions are not changed.  This is the only hledger command that+writes to the journal file.++   To use it, just run 'hledger add' and follow the prompts.  You can+add as many transactions as you like; when you are finished, enter '.'+or press control-d or control-c to exit.++   Features:++   * add tries to provide useful defaults, using the most similar (by+     description) recent transaction (filtered by the query, if any) as+     a template.+   * You can also set the initial defaults with command line arguments.+   * Readline-style edit keys can be used during data entry.+   * The tab key will auto-complete whenever possible - accounts,+     descriptions, dates ('yesterday', 'today', 'tomorrow').  If the+     input area is empty, it will insert the default value.+   * If the journal defines a default commodity, it will be added to any+     bare numbers entered.+   * A parenthesised transaction code may be entered following a date.+   * Comments and tags may be entered following a description or amount.+   * If you make a mistake, enter '<' at any prompt to go one step+     backward.+   * Input prompts are displayed in a different colour when the terminal+     supports it.++   Example (see the tutorial for a detailed explanation):++$ hledger add+Adding transactions to journal file /src/hledger/examples/sample.journal+Any command line arguments will be used as defaults.+Use tab key to complete, readline keys to edit, enter to accept defaults.+An optional (CODE) may follow transaction dates.+An optional ; COMMENT may follow descriptions or amounts.+If you make a mistake, enter < at any prompt to go one step backward.+To end a transaction, enter . when prompted.+To quit, enter . at a date prompt or press control-d or control-c.+Date [2015/05/22]: +Description: supermarket+Account 1: expenses:food+Amount  1: $10+Account 2: assets:checking+Amount  2 [$-10.0]: +Account 3 (or . or enter to finish this transaction): .+2015/05/22 supermarket+    expenses:food             $10+    assets:checking        $-10.0++Save this transaction to the journal ? [y]: +Saved.+Starting the next transaction (. or ctrl-D/ctrl-C to quit)+Date [2015/05/22]: <CTRL-D> $++   On Microsoft Windows, the add command makes sure that no part of the+file path ends with a period, as that would cause problems (#1056).+++File: hledger.info,  Node: aregister,  Next: balance,  Prev: add,  Up: COMMANDS++11.4 aregister+==============++aregister, areg++   Show the transactions and running historical balance of a single+account, with each transaction displayed as one line.++   'aregister' shows the overall transactions affecting a particular+account (and any subaccounts).  Each report line represents one+transaction in this account.  Transactions before the report start date+are always included in the running balance ('--historical' mode is+always on).++   This is a more "real world", bank-like view than the 'register'+command (which shows individual postings, possibly from multiple+accounts, not necessarily in historical mode).  As a quick rule of+thumb: - use 'aregister' for reviewing and reconciling real-world+asset/liability accounts - use 'register' for reviewing detailed+revenues/expenses.++   'aregister' requires one argument: the account to report on.  You can+write either the full account name, or a case-insensitive regular+expression which will select the alphabetically first matched account.+(Eg if you have 'assets:aaa:checking' and 'assets:bbb:checking'+accounts, 'hledger areg checking' would select 'assets:aaa:checking'.)++   Transactions involving subaccounts of this account will also be+shown.  'aregister' ignores depth limits, so its final total will always+match a balance report with similar arguments.++   Any additional arguments form a query which will filter the+transactions shown.  Note some queries will disturb the running balance,+causing it to be different from the account's real-world running+balance.++   An example: this shows the transactions and historical running+balance during july, in the first account whose name contains+"checking":++$ hledger areg checking date:jul++   Each 'aregister' line item shows:++   * the transaction's date (or the relevant posting's date if+     different, see below)+   * the names of all the other account(s) involved in this transaction+     (probably abbreviated)+   * the total change to this account's balance from this transaction+   * the account's historical running balance after this transaction.++   Transactions making a net change of zero are not shown by default;+add the '-E/--empty' flag to show them.++   This command also supports the output destination and output format+options.  The output formats supported are 'txt', 'csv', and 'json'.++* Menu:++* aregister and custom posting dates::+++File: hledger.info,  Node: aregister and custom posting dates,  Up: aregister++11.4.1 aregister and custom posting dates+-----------------------------------------++Transactions whose date is outside the report period can still be shown,+if they have a posting to this account dated inside the report period.+(And in this case it's the posting date that is shown.)  This ensures+that 'aregister' can show an accurate historical running balance,+matching the one shown by 'register -H' with the same arguments.++   To filter strictly by transaction date instead, add the '--txn-dates'+flag.  If you use this flag and some of your postings have custom dates,+it's probably best to assume the running balance is wrong.+++File: hledger.info,  Node: balance,  Next: balancesheet,  Prev: aregister,  Up: COMMANDS++11.5 balance+============++balance, bal+Show accounts and their balances.++   'balance' is one of hledger's oldest and most versatile commands, for+listing account balances, balance changes, values, value changes and+more, during one time period or many.  Generally it shows a table, with+rows representing accounts, and columns representing periods.++   Note there are some higher-level variants of the 'balance' command+with convenient defaults, which can be simpler to use: 'balancesheet',+'balancesheetequity', 'cashflow' and 'incomestatement'.  When you need+more control, then use 'balance'.++* Menu:++* balance features::+* Simple balance report::+* Filtered balance report::+* List or tree mode::+* Depth limiting::+* Dropping top-level accounts::+* Multi-period balance report::+* Showing declared accounts::+* Data layout::+* Sorting by amount::+* Percentages::+* Balance change end balance::+* Balance report types::+* Useful balance reports::+* Budget report::+* Customising single-period balance reports::+++File: hledger.info,  Node: balance features,  Next: Simple balance report,  Up: balance++11.5.1 balance features+-----------------------++Here's a quick overview of the 'balance' command's features, followed by+more detailed descriptions and examples.  Many of these work with the+higher-level commands as well.++   'balance' can show..++   * accounts as a list ('-l') or a tree ('-t')+   * optionally depth-limited ('-[1-9]')+   * sorted by declaration order and name, or by amount++   ..and their..++   * balance changes (the default)+   * or actual and planned balance changes ('--budget')+   * or value of balance changes ('-V')+   * or change of balance values ('--valuechange')+   * or unrealised capital gain/loss ('--gain')++   ..in..++   * one time period (the whole journal period by default)+   * or multiple periods ('-D', '-W', '-M', '-Q', '-Y', '-p INTERVAL')++   ..either..++   * per period (the default)+   * or accumulated since report start date ('--cumulative')+   * or accumulated since account creation ('--historical/-H')++   ..possibly converted to..++   * cost ('--value=cost[,COMM]'/'--cost'/'-B')+   * or market value, as of transaction dates ('--value=then[,COMM]')+   * or at period ends ('--value=end[,COMM]')+   * or now ('--value=now')+   * or at some other date ('--value=YYYY-MM-DD')++   ..with..++   * totals ('-T'), averages ('-A'), percentages ('-%'), inverted sign+     ('--invert')+   * rows and columns swapped ('--transpose')+   * another field used as account name ('--pivot')+   * custom-formatted line items (single-period reports only)+     ('--format')+   * commodities displayed on the same line or multiple lines+     ('--layout')++   This command supports the output destination and output format+options, with output formats 'txt', 'csv', 'json', and (multi-period+reports only:) 'html'.  In 'txt' output in a colour-supporting terminal,+negative amounts are shown in red.++   The '--related'/'-r' flag shows the balance of the _other_ postings+in the transactions of the postings which would normally be shown.+++File: hledger.info,  Node: Simple balance report,  Next: Filtered balance report,  Prev: balance features,  Up: balance++11.5.2 Simple balance report+----------------------------++With no arguments, 'balance' shows a list of all accounts and their+change of balance - ie, the sum of posting amounts, both inflows and+outflows - during the entire period of the journal.  For real-world+accounts, this should also match their end balance at the end of the+journal period (more on this below).++   Accounts are sorted by declaration order if any, and then+alphabetically by account name.  For instance (using+examples/sample.journal):++$ hledger -f examples/sample.journal bal+                  $1  assets:bank:saving+                 $-2  assets:cash+                  $1  expenses:food+                  $1  expenses:supplies+                 $-1  income:gifts+                 $-1  income:salary+                  $1  liabilities:debts+--------------------+                   0  ++   Accounts with a zero balance (and no non-zero subaccounts, in tree+mode - see below) are hidden by default.  Use '-E/--empty' to show them+(revealing 'assets:bank:checking' here):++$ hledger -f examples/sample.journal bal  -E+                   0  assets:bank:checking+                  $1  assets:bank:saving+                 $-2  assets:cash+                  $1  expenses:food+                  $1  expenses:supplies+                 $-1  income:gifts+                 $-1  income:salary+                  $1  liabilities:debts+--------------------+                   0  ++   The total of the amounts displayed is shown as the last line, unless+'-N'/'--no-total' is used.+++File: hledger.info,  Node: Filtered balance report,  Next: List or tree mode,  Prev: Simple balance report,  Up: balance++11.5.3 Filtered balance report+------------------------------++You can show fewer accounts, a different time period, totals from+cleared transactions only, etc.  by using query arguments or options to+limit the postings being matched.  Eg:++$ hledger -f examples/sample.journal bal --cleared assets date:200806+                 $-2  assets:cash+--------------------+                 $-2  +++File: hledger.info,  Node: List or tree mode,  Next: Depth limiting,  Prev: Filtered balance report,  Up: balance++11.5.4 List or tree mode+------------------------++By default, or with '-l/--flat', accounts are shown as a flat list with+their full names visible, as in the examples above.++   With '-t/--tree', the account hierarchy is shown, with subaccounts'+"leaf" names indented below their parent:++$ hledger -f examples/sample.journal balance+                 $-1  assets+                  $1    bank:saving+                 $-2    cash+                  $2  expenses+                  $1    food+                  $1    supplies+                 $-2  income+                 $-1    gifts+                 $-1    salary+                  $1  liabilities:debts+--------------------+                   0++   Notes:++   * "Boring" accounts are combined with their subaccount for more+     compact output, unless '--no-elide' is used.  Boring accounts have+     no balance of their own and just one subaccount (eg 'assets:bank'+     and 'liabilities' above).++   * All balances shown are "inclusive", ie including the balances from+     all subaccounts.  Note this means some repetition in the output,+     which requires explanation when sharing reports with+     non-plaintextaccounting-users.  A tree mode report's final total is+     the sum of the top-level balances shown, not of all the balances+     shown.++   * Each group of sibling accounts (ie, under a common parent) is+     sorted separately.+++File: hledger.info,  Node: Depth limiting,  Next: Dropping top-level accounts,  Prev: List or tree mode,  Up: balance++11.5.5 Depth limiting+---------------------++With a 'depth:NUM' query, or '--depth NUM' option, or just '-NUM' (eg:+'-3') balance reports will show accounts only to the specified depth,+hiding the deeper subaccounts.  This can be useful for getting an+overview without too much detail.++   Account balances at the depth limit always include the balances from+any deeper subaccounts (even in list mode).  Eg, limiting to depth 1:++$ hledger -f examples/sample.journal balance -1+                 $-1  assets+                  $2  expenses+                 $-2  income+                  $1  liabilities+--------------------+                   0  +++File: hledger.info,  Node: Dropping top-level accounts,  Next: Multi-period balance report,  Prev: Depth limiting,  Up: balance++11.5.6 Dropping top-level accounts+----------------------------------++You can also hide one or more top-level account name parts, using+'--drop NUM'.  This can be useful for hiding repetitive top-level+account names:++$ hledger -f examples/sample.journal bal expenses --drop 1+                  $1  food+                  $1  supplies+--------------------+                  $2  +++File: hledger.info,  Node: Multi-period balance report,  Next: Showing declared accounts,  Prev: Dropping top-level accounts,  Up: balance++11.5.7 Multi-period balance report+----------------------------------++With a report interval (set by the '-D/--daily', '-W/--weekly',+'-M/--monthly', '-Q/--quarterly', '-Y/--yearly', or '-p/--period' flag),+'balance' shows a tabular report, with columns representing successive+time periods (and a title):++$ hledger -f examples/sample.journal bal --quarterly income expenses -E+Balance changes in 2008:++                   ||  2008q1  2008q2  2008q3  2008q4 +===================++=================================+ expenses:food     ||       0      $1       0       0 + expenses:supplies ||       0      $1       0       0 + income:gifts      ||       0     $-1       0       0 + income:salary     ||     $-1       0       0       0 +-------------------++---------------------------------+                   ||     $-1      $1       0       0 ++   Notes:++   * The report's start/end dates will be expanded, if necessary, to+     fully encompass the displayed subperiods (so that the first and+     last subperiods have the same duration as the others).+   * Leading and trailing periods (columns) containing all zeroes are+     not shown, unless '-E/--empty' is used.+   * Accounts (rows) containing all zeroes are not shown, unless+     '-E/--empty' is used.+   * Amounts with many commodities are shown in abbreviated form, unless+     '--no-elide' is used.  _(experimental)_+   * Average and/or total columns can be added with the '-A/--average'+     and '-T/--row-total' flags.+   * The '--transpose' flag can be used to exchange rows and columns.+   * The '--pivot FIELD' option causes a different transaction field to+     be used as "account name".  See PIVOTING.++   Multi-period reports with many periods can be too wide for easy+viewing in the terminal.  Here are some ways to handle that:++   * Hide the totals row with '-N/--no-total'+   * Convert to a single currency with '-V'+   * Maximize the terminal window+   * Reduce the terminal's font size+   * View with a pager like less, eg: 'hledger bal -D --color=yes | less+     -RS'+   * Output as CSV and use a CSV viewer like visidata ('hledger bal -D+     -O csv | vd -f csv'), Emacs' csv-mode ('M-x csv-mode, C-c C-a'), or+     a spreadsheet ('hledger bal -D -o a.csv && open a.csv')+   * Output as HTML and view with a browser: 'hledger bal -D -o a.html+     && open a.html'+++File: hledger.info,  Node: Showing declared accounts,  Next: Data layout,  Prev: Multi-period balance report,  Up: balance++11.5.8 Showing declared accounts+--------------------------------++With '--declared', accounts which have been declared with an account+directive will be included in the balance report, even if they have no+transactions.  (Since they will have a zero balance, you will also need+'-E/--empty' to see them.)++   More precisely, _leaf_ declared accounts (with no subaccounts) will+be included, since those are usually the more useful in reports.++   The idea of this is to be able to see a useful "complete" balance+report, even when you don't have transactions in all of your declared+accounts yet.+++File: hledger.info,  Node: Data layout,  Next: Sorting by amount,  Prev: Showing declared accounts,  Up: balance++11.5.9 Data layout+------------------++The '--layout' option affects how multi-commodity amounts are displayed,+and some other things, influencing the overall layout of the report+data:++   * '--layout=wide[,WIDTH]': commodities are shown on a single line,+     possibly elided to the specified width+   * '--layout=tall': each commodity is shown on a separate line+   * '--layout=bare': amounts are shown as bare numbers, with commodity+     symbols in a separate column+   * '--layout=tidy': data is normalised to tidy form, with one row per+     data value.  We currently support this with CSV output only.  In+     tidy mode, totals and row averages are disabled ('-N/--no-total' is+     implied and '-T/--row-total' and '-A/--average' will be ignored).++   These '--layout' modes are supported with some but not all of the+output formats:++-      txt   csv   html   json   sql+---------------------------------------+wide   Y     Y     Y+tall   Y     Y     Y+bare   Y     Y     Y+tidy         Y++   Examples:++   * Wide layout.  With many commodities, reports can be very wide:++     $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide+     Balance changes in 2012-01-01..2014-12-31:+     +                       ||                                          2012                                                     2013                                             2014                                                      Total +     ==================++====================================================================================================================================================================================================================+      Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT  70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT  -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT  70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT +     ------------------++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+                       || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT  70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT  -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT  70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT ++   * Limited wide layout.  A width limit reduces the width, but some+     commodities will be hidden:++     $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32+     Balance changes in 2012-01-01..2014-12-31:+     +                       ||                             2012                             2013                   2014                            Total +     ==================++===========================================================================================================================+      Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more..  70.00 GLD, 18.00 ITOT, 3 more..  -11.00 ITOT, 3 more..  70.00 GLD, 17.00 ITOT, 3 more.. +     ------------------++---------------------------------------------------------------------------------------------------------------------------+                       || 10.00 ITOT, 337.18 USD, 2 more..  70.00 GLD, 18.00 ITOT, 3 more..  -11.00 ITOT, 3 more..  70.00 GLD, 17.00 ITOT, 3 more.. ++   * Tall layout.  Each commodity gets a new line (may be different in+     each column), and account names are repeated:++     $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall+     Balance changes in 2012-01-01..2014-12-31:+     +                       ||       2012        2013         2014        Total +     ==================++==================================================+      Assets:US:ETrade || 10.00 ITOT   70.00 GLD  -11.00 ITOT    70.00 GLD +      Assets:US:ETrade || 337.18 USD  18.00 ITOT  4881.44 USD   17.00 ITOT +      Assets:US:ETrade ||  12.00 VEA  -98.12 USD    14.00 VEA  5120.50 USD +      Assets:US:ETrade || 106.00 VHT   10.00 VEA   170.00 VHT    36.00 VEA +      Assets:US:ETrade ||              18.00 VHT                294.00 VHT +     ------------------++--------------------------------------------------+                       || 10.00 ITOT   70.00 GLD  -11.00 ITOT    70.00 GLD +                       || 337.18 USD  18.00 ITOT  4881.44 USD   17.00 ITOT +                       ||  12.00 VEA  -98.12 USD    14.00 VEA  5120.50 USD +                       || 106.00 VHT   10.00 VEA   170.00 VHT    36.00 VEA +                       ||              18.00 VHT                294.00 VHT ++   * Bare layout.  Commodity symbols are kept in one column, each+     commodity gets its own report row, account names are repeated:++     $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare+     Balance changes in 2012-01-01..2014-12-31:+     +                       || Commodity    2012    2013     2014    Total +     ==================++=============================================+      Assets:US:ETrade || GLD             0   70.00        0    70.00 +      Assets:US:ETrade || ITOT        10.00   18.00   -11.00    17.00 +      Assets:US:ETrade || USD        337.18  -98.12  4881.44  5120.50 +      Assets:US:ETrade || VEA         12.00   10.00    14.00    36.00 +      Assets:US:ETrade || VHT        106.00   18.00   170.00   294.00 +     ------------------++---------------------------------------------+                       || GLD             0   70.00        0    70.00 +                       || ITOT        10.00   18.00   -11.00    17.00 +                       || USD        337.18  -98.12  4881.44  5120.50 +                       || VEA         12.00   10.00    14.00    36.00 +                       || VHT        106.00   18.00   170.00   294.00 ++   * Bare layout also affects CSV output, which is useful for producing+     data that is easier to consume, eg when making charts:++     $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare+     "account","commodity","balance"+     "Assets:US:ETrade","GLD","70.00"+     "Assets:US:ETrade","ITOT","17.00"+     "Assets:US:ETrade","USD","5120.50"+     "Assets:US:ETrade","VEA","36.00"+     "Assets:US:ETrade","VHT","294.00"+     "total","GLD","70.00"+     "total","ITOT","17.00"+     "total","USD","5120.50"+     "total","VEA","36.00"+     "total","VHT","294.00"++   * Tidy layout produces normalised "tidy data", where every variable+     is a column and each row represents a single data point (see+     https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html).+     This kind of data is the easiest to process with other software:++     $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy+     "account","period","start_date","end_date","commodity","value"+     "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0"+     "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00"+     "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18"+     "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00"+     "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00"+     "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00"+     "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00"+     "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12"+     "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00"+     "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00"+     "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0"+     "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00"+     "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44"+     "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00"+     "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00"+++File: hledger.info,  Node: Sorting by amount,  Next: Percentages,  Prev: Data layout,  Up: balance++11.5.10 Sorting by amount+-------------------------++With '-S/--sort-amount', accounts with the largest (most positive)+balances are shown first.  Eg: 'hledger bal expenses -MAS' shows your+biggest averaged monthly expenses first.  When more than one commodity+is present, they will be sorted by the alphabetically earliest commodity+first, and then by subsequent commodities (if an amount is missing a+commodity, it is treated as 0).++   Revenues and liability balances are typically negative, however, so+'-S' shows these in reverse order.  To work around this, you can add+'--invert' to flip the signs.  (Or, use one of the higher-level reports,+which flip the sign automatically.  Eg: 'hledger incomestatement -MAS').+++File: hledger.info,  Node: Percentages,  Next: Balance change end balance,  Prev: Sorting by amount,  Up: balance++11.5.11 Percentages+-------------------++With '-%/--percent', balance reports show each account's value expressed+as a percentage of the (column) total:++$ hledger -f examples/sample.journal bal expenses -Q -%+Balance changes in 2008:++                   || 2008Q1   2008Q2  2008Q3  2008Q4 +===================++=================================+ expenses:food     ||      0   50.0 %       0       0 + expenses:supplies ||      0   50.0 %       0       0 +-------------------++---------------------------------+                   ||      0  100.0 %       0       0 ++   Note it is not useful to calculate percentages if the amounts in a+column have mixed signs.  In this case, make a separate report for each+sign, eg:++$ hledger bal -% amt:`>0`+$ hledger bal -% amt:`<0`++   Similarly, if the amounts in a column have mixed commodities, convert+them to one commodity with '-B', '-V', '-X' or '--value', or make a+separate report for each commodity:++$ hledger bal -% cur:\\$+$ hledger bal -% cur:€+++File: hledger.info,  Node: Balance change end balance,  Next: Balance report types,  Prev: Percentages,  Up: balance++11.5.12 Balance change, end balance+-----------------------------------++It's important to be clear on the meaning of the numbers shown in+balance reports.  Here is some terminology we use:++   A *_balance change_* is the net amount added to, or removed from, an+account during some period.++   An *_end balance_* is the amount accumulated in an account as of some+date (and some time, but hledger doesn't store that; assume end of day+in your timezone).  It is the sum of previous balance changes.++   We call it a *_historical end balance_* if it includes all balance+changes since the account was created.  For a real world account, this+means it will match the "historical record", eg the balances reported in+your bank statements or bank web UI. (If they are correct!)++   In general, balance changes are what you want to see when reviewing+revenues and expenses, and historical end balances are what you want to+see when reviewing or reconciling asset, liability and equity accounts.++   'balance' shows balance changes by default.  To see accurate+historical end balances:++  1. Initialise account starting balances with an "opening balances"+     transaction (a transfer from equity to the account), unless the+     journal covers the account's full lifetime.++  2. Include all of of the account's prior postings in the report, by+     not specifying a report start date, or by using the+     '-H/--historical' flag.  ('-H' causes report start date to be+     ignored when summing postings.)+++File: hledger.info,  Node: Balance report types,  Next: Useful balance reports,  Prev: Balance change end balance,  Up: balance++11.5.13 Balance report types+----------------------------++For more flexible reporting, there are three important option groups:++   'hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE]+...'++   The first two are the most important: calculation type selects the+basic calculation to perform for each table cell, while accumulation+type says which postings should be included in each cell's calculation.+Typically one or both of these are selected by default, so you don't+need to write them explicitly.  A valuation type can be added if you+want to convert the basic report to value or cost.++   *Calculation type:*+The basic calculation to perform for each table cell.  It is one of:++   * '--sum' : sum the posting amounts (*default*)+   * '--budget' : like -sum but also show a goal amount+   * '--valuechange' : show the change in period-end historical balance+     values (caused by deposits, withdrawals, and/or market price+     fluctuations)+   * '--gain' : show the unrealised capital gain/loss, (the current+     valued balance minus each amount's original cost)++   *Accumulation type:*+Which postings should be included in each cell's calculation.  It is one+of:++   * '--change' : postings from column start to column end, ie within+     the cell's period.  Typically used to see revenues/expenses.+     (*default for balance, incomestatement*)++   * '--cumulative' : postings from report start to column end, eg to+     show changes accumulated since the report's start date.  Rarely+     used.++   * '--historical/-H' : postings from journal start to column end, ie+     all postings from account creation to the end of the cell's period.+     Typically used to see historical end balances of+     assets/liabilities/equity.  (*default for balancesheet,+     balancesheetequity, cashflow*)++   *Valuation type:*+Which kind of valuation, valuation date(s) and optionally a target+valuation commodity to use.  It is one of:++   * no valuation, show amounts in their original commodities+     (*default*)+   * '--value=cost[,COMM]' : no valuation, show amounts converted to+     cost+   * '--value=then[,COMM]' : show value at transaction dates+   * '--value=end[,COMM]' : show value at period end date(s) (*default+     with '--valuechange', '--gain'*)+   * '--value=now[,COMM]' : show value at today's date+   * '--value=YYYY-MM-DD[,COMM]' : show value at another date++   or one of their aliases: '--cost/-B', '--market/-V' or+'--exchange/-X'.++   Most combinations of these options should produce reasonable reports,+but if you find any that seem wrong or misleading, let us know.  The+following restrictions are applied:++   * '--valuechange' implies '--value=end'+   * '--valuechange' makes '--change' the default when used with the+     'balancesheet'/'balancesheetequity' commands+   * '--cumulative' or '--historical' disables '--row-total/-T'++   For reference, here is what the combinations of accumulation and+valuation show:++Valuation:no valuation      '--value= then'   '--value= end'   '--value=+>Accumulation:                                                 YYYY-MM-DD+v                                                              /now'+------------------------------------------------------------------------------+'--change'change in         sum of            period-end       DATE-value+          period            posting-date      value of         of change in+                            market values     change in        period+                            in period         period+'--cumulative'change from   sum of            period-end       DATE-value+          report start to   posting-date      value of         of change+          period end        market values     change from      from report+                            from report       report start     start to+                            start to period   to period end    period end+                            end+'--historicalchange from    sum of            period-end       DATE-value+/-H'      journal start     posting-date      value of         of change+          to period end     market values     change from      from journal+          (historical end   from journal      journal start    start to+          balance)          start to period   to period end    period end+                            end+++File: hledger.info,  Node: Useful balance reports,  Next: Budget report,  Prev: Balance report types,  Up: balance++11.5.14 Useful balance reports+------------------------------++Some frequently used 'balance' options/reports are:++   * 'bal -M revenues expenses'+     Show revenues/expenses in each month.  Also available as the+     'incomestatement' command.++   * 'bal -M -H assets liabilities'+     Show historical asset/liability balances at each month end.  Also+     available as the 'balancesheet' command.++   * 'bal -M -H assets liabilities equity'+     Show historical asset/liability/equity balances at each month end.+     Also available as the 'balancesheetequity' command.++   * 'bal -M assets not:receivable'+     Show changes to liquid assets in each month.  Also available as the+     'cashflow' command.++   Also:++   * 'bal -M expenses -2 -SA'+     Show monthly expenses summarised to depth 2 and sorted by average+     amount.++   * 'bal -M --budget expenses'+     Show monthly expenses and budget goals.++   * 'bal -M --valuechange investments'+     Show monthly change in market value of investment assets.++   * 'bal investments --valuechange -D date:lastweek amt:'>1000' -STA+     [--invert]'+     Show top gainers [or losers] last week+++File: hledger.info,  Node: Budget report,  Next: Customising single-period balance reports,  Prev: Useful balance reports,  Up: balance++11.5.15 Budget report+---------------------++The '--budget' report type activates extra columns showing any budget+goals for each account and period.  The budget goals are defined by+periodic transactions.  This is very useful for comparing planned and+actual income, expenses, time usage, etc.++   For example, you can take average monthly expenses in the common+expense categories to construct a minimal monthly budget:++;; Budget+~ monthly+  income  $2000+  expenses:food    $400+  expenses:bus     $50+  expenses:movies  $30+  assets:bank:checking++;; Two months worth of expenses+2017-11-01+  income  $1950+  expenses:food    $396+  expenses:bus     $49+  expenses:movies  $30+  expenses:supplies  $20+  assets:bank:checking++2017-12-01+  income  $2100+  expenses:food    $412+  expenses:bus     $53+  expenses:gifts   $100+  assets:bank:checking++   You can now see a monthly budget report:++$ hledger balance -M --budget+Budget performance in 2017/11/01-2017/12/31:++                      ||                      Nov                       Dec +======================++====================================================+ assets               || $-2445 [  99% of $-2480]  $-2665 [ 107% of $-2480] + assets:bank          || $-2445 [  99% of $-2480]  $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [  99% of $-2480]  $-2665 [ 107% of $-2480] + expenses             ||   $495 [ 103% of   $480]    $565 [ 118% of   $480] + expenses:bus         ||    $49 [  98% of    $50]     $53 [ 106% of    $50] + expenses:food        ||   $396 [  99% of   $400]    $412 [ 103% of   $400] + expenses:movies      ||    $30 [ 100% of    $30]       0 [   0% of    $30] + income               ||  $1950 [  98% of  $2000]   $2100 [ 105% of  $2000] +----------------------++----------------------------------------------------+                      ||      0 [              0]       0 [              0] ++   This is different from a normal balance report in several ways:++   * Only accounts with budget goals during the report period are shown,+     by default.++   * In each column, in square brackets after the actual amount, budget+     goal amounts are shown, and the actual/goal percentage.  (Note:+     budget goals should be in the same commodity as the actual amount.)++   * All parent accounts are always shown, even in list mode.  Eg+     assets, assets:bank, and expenses above.++   * Amounts always include all subaccounts, budgeted or unbudgeted,+     even in list mode.++   This means that the numbers displayed will not always add up!  Eg+above, the 'expenses' actual amount includes the gifts and supplies+transactions, but the 'expenses:gifts' and 'expenses:supplies' accounts+are not shown, as they have no budget amounts declared.++   This can be confusing.  When you need to make things clearer, use the+'-E/--empty' flag, which will reveal all accounts including unbudgeted+ones, giving the full picture.  Eg:++$ hledger balance -M --budget --empty+Budget performance in 2017/11/01-2017/12/31:++                      ||                      Nov                       Dec +======================++====================================================+ assets               || $-2445 [  99% of $-2480]  $-2665 [ 107% of $-2480] + assets:bank          || $-2445 [  99% of $-2480]  $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [  99% of $-2480]  $-2665 [ 107% of $-2480] + expenses             ||   $495 [ 103% of   $480]    $565 [ 118% of   $480] + expenses:bus         ||    $49 [  98% of    $50]     $53 [ 106% of    $50] + expenses:food        ||   $396 [  99% of   $400]    $412 [ 103% of   $400] + expenses:gifts       ||      0                      $100                   + expenses:movies      ||    $30 [ 100% of    $30]       0 [   0% of    $30] + expenses:supplies    ||    $20                         0                   + income               ||  $1950 [  98% of  $2000]   $2100 [ 105% of  $2000] +----------------------++----------------------------------------------------+                      ||      0 [              0]       0 [              0] ++   You can roll over unspent budgets to next period with '--cumulative':++$ hledger balance -M --budget --cumulative+Budget performance in 2017/11/01-2017/12/31:++                      ||                      Nov                       Dec +======================++====================================================+ assets               || $-2445 [  99% of $-2480]  $-5110 [ 103% of $-4960] + assets:bank          || $-2445 [  99% of $-2480]  $-5110 [ 103% of $-4960] + assets:bank:checking || $-2445 [  99% of $-2480]  $-5110 [ 103% of $-4960] + expenses             ||   $495 [ 103% of   $480]   $1060 [ 110% of   $960] + expenses:bus         ||    $49 [  98% of    $50]    $102 [ 102% of   $100] + expenses:food        ||   $396 [  99% of   $400]    $808 [ 101% of   $800] + expenses:movies      ||    $30 [ 100% of    $30]     $30 [  50% of    $60] + income               ||  $1950 [  98% of  $2000]   $4050 [ 101% of  $4000] +----------------------++----------------------------------------------------+                      ||      0 [              0]       0 [              0] ++   For more examples and notes, see Budgeting.++* Menu:++* Budget report start date::+* Budgets and subaccounts::+* Selecting budget goals::+++File: hledger.info,  Node: Budget report start date,  Next: Budgets and subaccounts,  Up: Budget report++11.5.15.1 Budget report start date+..................................++This might be a bug, but for now: when making budget reports, it's a+good idea to explicitly set the report's start date to the first day of+a reporting period, because a periodic rule like '~ monthly' generates+its transactions on the 1st of each month, and if your journal has no+regular transactions on the 1st, the default report start date could+exclude that budget goal, which can be a little surprising.  Eg here the+default report period is just the day of 2020-01-15:++~ monthly in 2020+  (expenses:food)  $500++2020-01-15+  expenses:food    $400+  assets:checking++$ hledger bal expenses --budget+Budget performance in 2020-01-15:++              || 2020-01-15 +==============++============+ <unbudgeted> ||       $400 +--------------++------------+              ||       $400 ++   To avoid this, specify the budget report's period, or at least the+start date, with '-b'/'-e'/'-p'/'date:', to ensure it includes the+budget goal transactions (periodic transactions) that you want.  Eg,+adding '-b 2020/1/1' to the above:++$ hledger bal expenses --budget -b 2020/1/1+Budget performance in 2020-01-01..2020-01-15:++               || 2020-01-01..2020-01-15 +===============++========================+ expenses:food ||     $400 [80% of $500] +---------------++------------------------+               ||     $400 [80% of $500] +++File: hledger.info,  Node: Budgets and subaccounts,  Next: Selecting budget goals,  Prev: Budget report start date,  Up: Budget report++11.5.15.2 Budgets and subaccounts+.................................++You can add budgets to any account in your account hierarchy.  If you+have budgets on both parent account and some of its children, then+budget(s) of the child account(s) would be added to the budget of their+parent, much like account balances behave.++   In the most simple case this means that once you add a budget to any+account, all its parents would have budget as well.++   To illustrate this, consider the following budget:++~ monthly from 2019/01+    expenses:personal             $1,000.00+    expenses:personal:electronics    $100.00+    liabilities++   With this, monthly budget for electronics is defined to be $100 and+budget for personal expenses is an additional $1000, which implicitly+means that budget for both 'expenses:personal' and 'expenses' is $1100.++   Transactions in 'expenses:personal:electronics' will be counted both+towards its $100 budget and $1100 of 'expenses:personal' , and+transactions in any other subaccount of 'expenses:personal' would be+counted towards only towards the budget of 'expenses:personal'.++   For example, let's consider these transactions:++~ monthly from 2019/01+    expenses:personal             $1,000.00+    expenses:personal:electronics    $100.00+    liabilities++2019/01/01 Google home hub+    expenses:personal:electronics          $90.00+    liabilities                           $-90.00++2019/01/02 Phone screen protector+    expenses:personal:electronics:upgrades          $10.00+    liabilities++2019/01/02 Weekly train ticket+    expenses:personal:train tickets       $153.00+    liabilities++2019/01/03 Flowers+    expenses:personal          $30.00+    liabilities++   As you can see, we have transactions in+'expenses:personal:electronics:upgrades' and 'expenses:personal:train+tickets', and since both of these accounts are without explicitly+defined budget, these transactions would be counted towards budgets of+'expenses:personal:electronics' and 'expenses:personal' accordingly:++$ hledger balance --budget -M+Budget performance in 2019/01:++                               ||                           Jan +===============================++===============================+ expenses                      ||  $283.00 [  26% of  $1100.00] + expenses:personal             ||  $283.00 [  26% of  $1100.00] + expenses:personal:electronics ||  $100.00 [ 100% of   $100.00] + liabilities                   || $-283.00 [  26% of $-1100.00] +-------------------------------++-------------------------------+                               ||        0 [                 0] ++   And with '--empty', we can get a better picture of budget allocation+and consumption:++$ hledger balance --budget -M --empty+Budget performance in 2019/01:++                                        ||                           Jan +========================================++===============================+ expenses                               ||  $283.00 [  26% of  $1100.00] + expenses:personal                      ||  $283.00 [  26% of  $1100.00] + expenses:personal:electronics          ||  $100.00 [ 100% of   $100.00] + expenses:personal:electronics:upgrades ||   $10.00                      + expenses:personal:train tickets        ||  $153.00                      + liabilities                            || $-283.00 [  26% of $-1100.00] +----------------------------------------++-------------------------------+                                        ||        0 [                 0] +++File: hledger.info,  Node: Selecting budget goals,  Prev: Budgets and subaccounts,  Up: Budget report++11.5.15.3 Selecting budget goals+................................++The budget report evaluates periodic transaction rules to generate+special "goal transactions", which generate the goal amounts for each+account in each report subperiod.  When troubleshooting, you can use the+print command to show these as forecasted transactions:++$ hledger print --forecast=BUDGETREPORTPERIOD tag:generated++   By default, the budget report uses all available periodic transaction+rules to generate goals.  This includes rules with a different report+interval from your report.  Eg if you have daily, weekly and monthly+periodic rules, all of these will contribute to the goals in a monthly+budget report.++   You can select a subset of periodic rules by providing an argument to+the '--budget' flag.  '--budget=DESCPAT' will match all periodic rules+whose description contains DESCPAT, a case-insensitive substring (not a+regular expression or query).  This means you can give your periodic+rules descriptions (remember that two spaces are needed), and then+select from multiple budgets defined in your journal.+++File: hledger.info,  Node: Customising single-period balance reports,  Prev: Budget report,  Up: balance++11.5.16 Customising single-period balance reports+-------------------------------------------------++For single-period balance reports displayed in the terminal (only), you+can use '--format FMT' to customise the format and content of each line.+Eg:++$ hledger -f examples/sample.journal balance --format "%20(account) %12(total)"+              assets          $-1+         bank:saving           $1+                cash          $-2+            expenses           $2+                food           $1+            supplies           $1+              income          $-2+               gifts          $-1+              salary          $-1+   liabilities:debts           $1+---------------------------------+                                0++   The FMT format string (plus a newline) specifies the formatting+applied to each account/balance pair.  It may contain any suitable text,+with data fields interpolated like so:++   '%[MIN][.MAX](FIELDNAME)'++   * MIN pads with spaces to at least this width (optional)++   * MAX truncates at this width (optional)++   * FIELDNAME must be enclosed in parentheses, and can be one of:++        * 'depth_spacer' - a number of spaces equal to the account's+          depth, or if MIN is specified, MIN * depth spaces.+        * 'account' - the account's name+        * 'total' - the account's balance/posted total, right justified++   Also, FMT can begin with an optional prefix to control how+multi-commodity amounts are rendered:++   * '%_' - render on multiple lines, bottom-aligned (the default)+   * '%^' - render on multiple lines, top-aligned+   * '%,' - render on one line, comma-separated++   There are some quirks.  Eg in one-line mode, '%(depth_spacer)' has no+effect, instead '%(account)' has indentation built in.  Experimentation+may be needed to get pleasing results.++   Some example formats:++   * '%(total)' - the account's total+   * '%-20.20(account)' - the account's name, left justified, padded to+     20 characters and clipped at 20 characters+   * '%,%-50(account) %25(total)' - account name padded to 50+     characters, total padded to 20 characters, with multiple+     commodities rendered on one line+   * '%20(total) %2(depth_spacer)%-(account)' - the default format for+     the single-column balance report+++File: hledger.info,  Node: balancesheet,  Next: balancesheetequity,  Prev: balance,  Up: COMMANDS++11.6 balancesheet+=================++balancesheet, bs+This command displays a balance sheet, showing historical ending+balances of asset and liability accounts.  (To see equity as well, use+the balancesheetequity command.)  Amounts are shown with normal positive+sign, as in conventional financial statements.++   The asset and liability accounts shown are those accounts declared+with the 'Asset' or 'Cash' or 'Liability' type, or otherwise all+accounts under a top-level 'asset' or 'liability' account (case+insensitive, plurals allowed).++   Example:++$ hledger balancesheet+Balance Sheet++Assets:+                 $-1  assets+                  $1    bank:saving+                 $-2    cash+--------------------+                 $-1++Liabilities:+                  $1  liabilities:debts+--------------------+                  $1++Total:+--------------------+                   0++   This command is a higher-level variant of the 'balance' command, and+supports many of that command's features, such as multi-period reports.+It is similar to 'hledger balance -H assets liabilities', but with+smarter account detection, and liabilities displayed with their sign+flipped.++   This command also supports the output destination and output format+options The output formats supported are 'txt', 'csv', 'html', and+(experimental) 'json'.+++File: hledger.info,  Node: balancesheetequity,  Next: cashflow,  Prev: balancesheet,  Up: COMMANDS++11.7 balancesheetequity+=======================++balancesheetequity, bse+This command displays a balance sheet, showing historical ending+balances of asset, liability and equity accounts.  Amounts are shown+with normal positive sign, as in conventional financial statements.++   The asset, liability and equity accounts shown are those accounts+declared with the 'Asset', 'Cash', 'Liability' or 'Equity' type, or+otherwise all accounts under a top-level 'asset', 'liability' or+'equity' account (case insensitive, plurals allowed).++   Example:++$ hledger balancesheetequity+Balance Sheet With Equity++Assets:+                 $-2  assets+                  $1    bank:saving+                 $-3    cash+--------------------+                 $-2++Liabilities:+                  $1  liabilities:debts+--------------------+                  $1++Equity:+          $1  equity:owner+--------------------+          $1++Total:+--------------------+                   0++   This command is a higher-level variant of the 'balance' command, and+supports many of that command's features, such as multi-period reports.+It is similar to 'hledger balance -H assets liabilities equity', but+with smarter account detection, and liabilities/equity displayed with+their sign flipped.++   This command also supports the output destination and output format+options The output formats supported are 'txt', 'csv', 'html', and+(experimental) 'json'.+++File: hledger.info,  Node: cashflow,  Next: check,  Prev: balancesheetequity,  Up: COMMANDS++11.8 cashflow+=============++cashflow, cf+This command displays a cashflow statement, showing the inflows and+outflows affecting "cash" (ie, liquid) assets.  Amounts are shown with+normal positive sign, as in conventional financial statements.++   The "cash" accounts shown are those accounts declared with the 'Cash'+type, or otherwise all accounts under a top-level 'asset' account (case+insensitive, plural allowed) which do not have 'fixed', 'investment',+'receivable' or 'A/R' in their name.++   Example:++$ hledger cashflow+Cashflow Statement++Cash flows:+                 $-1  assets+                  $1    bank:saving+                 $-2    cash+--------------------+                 $-1++Total:+--------------------+                 $-1++   This command is a higher-level variant of the 'balance' command, and+supports many of that command's features, such as multi-period reports.+It is similar to 'hledger balance assets not:fixed not:investment+not:receivable', but with smarter account detection.++   This command also supports the output destination and output format+options The output formats supported are 'txt', 'csv', 'html', and+(experimental) 'json'.+++File: hledger.info,  Node: check,  Next: close,  Prev: cashflow,  Up: COMMANDS++11.9 check+==========++check+Check for various kinds of errors in your data.++   hledger provides a number of built-in error checks to help prevent+problems in your data.  Some of these are run automatically; or, you can+use this 'check' command to run them on demand, with no output and a+zero exit code if all is well.  Specify their names (or a prefix) as+argument(s).++   Some examples:++hledger check      # basic checks+hledger check -s   # basic + strict checks+hledger check ordereddates payees  # basic + two other checks++   Here are the checks currently available:++* Menu:++* Basic checks::+* Strict checks::+* Other checks::+* Custom checks::+++File: hledger.info,  Node: Basic checks,  Next: Strict checks,  Up: check++11.9.1 Basic checks+-------------------++These checks are always run automatically, by (almost) all hledger+commands, including 'check':++   * *parseable* - data files are well-formed and can be successfully+     parsed++   * *balancedwithautoconversion* - all transactions are balanced,+     inferring missing amounts where necessary, and possibly converting+     commodities using transaction prices or automatically-inferred+     transaction prices++   * *assertions* - all balance assertions in the journal are passing.+     (This check can be disabled with '-I'/'--ignore-assertions'.)+++File: hledger.info,  Node: Strict checks,  Next: Other checks,  Prev: Basic checks,  Up: check++11.9.2 Strict checks+--------------------++These additional checks are run when the '-s'/'--strict' (strict mode)+flag is used.  Or, they can be run by giving their names as arguments to+'check':++   * *accounts* - all account names used by transactions have been+     declared++   * *commodities* - all commodity symbols used have been declared++   * *balancednoautoconversion* - transactions are balanced, possibly+     using explicit transaction prices but not inferred ones+++File: hledger.info,  Node: Other checks,  Next: Custom checks,  Prev: Strict checks,  Up: check++11.9.3 Other checks+-------------------++These checks can be run only by giving their names as arguments to+'check'.  They are more specialised and not desirable for everyone,+therefore optional:++   * *ordereddates* - transactions are ordered by date within each file++   * *payees* - all payees used by transactions have been declared++   * *uniqueleafnames* - all account leaf names are unique+++File: hledger.info,  Node: Custom checks,  Prev: Other checks,  Up: check++11.9.4 Custom checks+--------------------++A few more checks are are available as separate add-on commands, in+https://github.com/simonmichael/hledger/tree/master/bin:++   * *hledger-check-tagfiles* - all tag values containing / (a forward+     slash) exist as file paths++   * *hledger-check-fancyassertions* - more complex balance assertions+     are passing++   You could make similar scripts to perform your own custom checks.+See: Cookbook -> Scripting.+++File: hledger.info,  Node: close,  Next: codes,  Prev: check,  Up: COMMANDS++11.10 close+===========++close, equity+Prints a sample "closing" transaction bringing specified account+balances to zero, and an inverse "opening" transaction restoring the+same account balances.++   If like most people you split your journal files by time, eg by year:+at the end of the year you can use this command to "close out" your+asset and liability (and perhaps equity) balances in the old file, and+reinitialise them in the new file.  This helps ensure that report+balances remain correct whether you are including old files or not.+(Because all closing/opening transactions except the very first will+cancel out - see example below.)++   Some people also use this command to close out revenue and expense+balances at the end of an accounting period.  This properly records the+period's profit/loss as "retained earnings" (part of equity), and allows+the accounting equation (A-L=E) to balance, which you could then check+by the bse report's zero total.++   You can print just the closing transaction by using the '--close'+flag, or just the opening transaction with the '--open' flag.++   Their descriptions are 'closing balances' and 'opening balances' by+default; you can customise these with the '--close-desc' and+'--open-desc' options.++   Just one balancing equity posting is used by default, with the amount+left implicit.  The default account name is 'equity:opening/closing+balances'.  You can customise the account name(s) with '--close-acct'+and '--open-acct'.  (If you specify only one of these, it will be used+for both.)++   With '--x/--explicit', the equity posting's amount will be shown+explicitly, and if it involves multiple commodities, there will be a+separate equity posting for each commodity (as in the print command).++   With '--interleaved', each equity posting is shown next to the+posting it balances (good for troubleshooting).++* Menu:++* close and prices::+* close date::+* Example close asset/liability accounts for file transition::+* Hiding opening/closing transactions::+* close and balance assertions::+* Example close revenue/expense accounts to retained earnings::+++File: hledger.info,  Node: close and prices,  Next: close date,  Up: close++11.10.1 close and prices+------------------------++Transaction prices are ignored (and discarded) by closing/opening+transactions, by default.  With '--show-costs', they are preserved;+there will be a separate equity posting for each cost in each commodity.+This means 'balance -B' reports will look the same after the transition.+Note if you have many foreign currency or investment transactions, this+will generate very large journal entries.+++File: hledger.info,  Node: close date,  Next: Example close asset/liability accounts for file transition,  Prev: close and prices,  Up: close++11.10.2 close date+------------------++The default closing date is yesterday, or the journal's end date,+whichever is later.++   Unless you are running 'close' on exactly the first day of the new+period, you'll want to override the closing date.  This is done by+specifying a report end date, where "last day of the report period" will+be the closing date.  The opening date is always the following day.  So+to close on (end of) 2020-12-31 and open on (start of) 2021-01-01, any+of these will work:++end date          explanation+argument+-------------------------------------------------------------------+'-e 2021-01-01'   end dates are exclusive+'-e 2021'         equivalent, per smart dates+'-p 2020'         equivalent, the period's begin date is ignored+'date:2020'       equivalent query+++File: hledger.info,  Node: Example close asset/liability accounts for file transition,  Next: Hiding opening/closing transactions,  Prev: close date,  Up: close++11.10.3 Example: close asset/liability accounts for file transition+-------------------------------------------------------------------++Carrying asset/liability balances from 2020.journal into a new file for+2021:++$ hledger close -f 2020.journal -p 2020 assets liabilities+# copy/paste the closing transaction to the end of 2020.journal+# copy/paste the opening transaction to the start of 2021.journal++   Or:++$ hledger close -f 2020.journal -p 2020 assets liabilities --open  >> 2021.journal  # add 2021's first transaction+$ hledger close -f 2020.journal -p 2020 assets liabilities --close >> 2020.journal  # add 2020's last transaction++   Now,++$ hledger bs -f 2021.journal                   # just new file - balances correct+$ hledger bs -f 2020.journal -f 2021.journal   # old and new files - balances correct+$ hledger bs -f 2020.journal                   # just old files - balances are zero ?+                                               # (exclude final closing txn, see below)+++File: hledger.info,  Node: Hiding opening/closing transactions,  Next: close and balance assertions,  Prev: Example close asset/liability accounts for file transition,  Up: close++11.10.4 Hiding opening/closing transactions+-------------------------------------------++Although the closing/opening transactions cancel out, they will be+visible in reports like 'print' and 'register', creating some visual+clutter.  You can exclude them all with a query, like:++$ hledger print not:desc:'opening|closing'             # less typing+$ hledger print not:'equity:opening/closing balances'  # more precise++   But when reporting on multiple files, this can get a bit tricky; you+may need to keep the earliest opening balances, for a historical+register report; or you may need to suppress a closing transaction, to+see year-end balances.  If you find yourself needing more precise+queries, here's one solution: add more easily-matched tags to+opening/closing transactions, like this:++; 2019.journal+2019-01-01 opening balances  ; earliest opening txn, no tag here+...+2019-12-31 closing balances  ; clopen:2020+...++; 2020.journal+2020-01-01 opening balances  ; clopen:2020+...+2020-12-31 closing balances  ; clopen:2021+...++; 2021.journal+2021-01-01 opening balances  ; clopen:2021+...++   Now with++; all.journal+include 2019.journal+include 2020.journal+include 2021.journal++   you could do eg:++$ hledger -f all.journal reg -H checking not:tag:clopen+    # all years checking register, hiding non-essential opening/closing txns++$ hledger -f all.journal bs -p 2020 not:tag:clopen=2020+    # 2020 year end balances, suppressing 2020 closing txn+++File: hledger.info,  Node: close and balance assertions,  Next: Example close revenue/expense accounts to retained earnings,  Prev: Hiding opening/closing transactions,  Up: close++11.10.5 close and balance assertions+------------------------------------++The closing and opening transactions will include balance assertions,+verifying that the accounts have first been reset to zero and then+restored to their previous balance.  These provide valuable error+checking, alerting you when things get out of line, but you can ignore+them temporarily with '-I' or just remove them if you prefer.++   You probably shouldn't use status or realness filters (like -C or -R+or 'status:') with 'close', or the generated balance assertions will+depend on these flags.  Likewise, if you run this command with '--auto',+the balance assertions would probably always require '--auto'.++   Multi-day transactions (where some postings have a different date)+break the balance assertions, because the money is temporarily+"invisible" while in transit:++2020/12/30 a purchase made in december, cleared in the next year+    expenses:food          5+    assets:bank:checking  -5  ; date: 2021/1/2++   To fix the assertions, you can add a temporary account to track such+in-transit money (splitting the multi-day transaction into two+single-day transactions):++; in 2020.journal:+2020/12/30 a purchase made in december, cleared in the next year+    expenses:food          5+    liabilities:pending++; in 2021.journal:+2021/1/2 clearance of last year's pending transactions+    liabilities:pending    5 = 0+    assets:bank:checking+++File: hledger.info,  Node: Example close revenue/expense accounts to retained earnings,  Prev: close and balance assertions,  Up: close++11.10.6 Example: close revenue/expense accounts to retained earnings+--------------------------------------------------------------------++For this, use '--close' to suppress the opening transaction, as it's not+needed.  Also you'll want to change the equity account name to your+equivalent of "equity:retained earnings".++   Closing 2021's first quarter revenues/expenses:++$ hledger close -f 2021.journal --close revenues expenses -p 2021Q1 \+    --close-acct='equity:retained earnings' >> 2021.journal++   The same, using the default journal and current year:++$ hledger close --close revenues expenses -p Q1 \+    --close-acct='equity:retained earnings' >> $LEDGER_FILE++   Now, the first quarter's balance sheet should show a zero (unless you+are using @/@@ notation without equity postings):++$ hledger bse -p Q1++   And we must suppress the closing transaction to see the first+quarter's income statement (using the description; 'not:'retained+earnings'' won't work here):++$ hledger is -p Q1 not:desc:'closing balances'+++File: hledger.info,  Node: codes,  Next: commodities,  Prev: close,  Up: COMMANDS++11.11 codes+===========++codes+List the codes seen in transactions, in the order parsed.++   This command prints the value of each transaction's code field, in+the order transactions were parsed.  The transaction code is an optional+value written in parentheses between the date and description, often+used to store a cheque number, order number or similar.++   Transactions aren't required to have a code, and missing or empty+codes will not be shown by default.  With the '-E'/'--empty' flag, they+will be printed as blank lines.++   You can add a query to select a subset of transactions.++   Examples:++1/1 (123)+ (a)  1++1/1 ()+ (a)  1++1/1+ (a)  1++1/1 (126)+ (a)  1++$ hledger codes+123+124+126++$ hledger codes -E+123+124+++126+++File: hledger.info,  Node: commodities,  Next: descriptions,  Prev: codes,  Up: COMMANDS++11.12 commodities+=================++commodities+List all commodity/currency symbols used or declared in the journal.+++File: hledger.info,  Node: descriptions,  Next: diff,  Prev: commodities,  Up: COMMANDS++11.13 descriptions+==================++descriptions+List the unique descriptions that appear in transactions.++   This command lists the unique descriptions that appear in+transactions, in alphabetic order.  You can add a query to select a+subset of transactions.++   Example:++$ hledger descriptions+Store Name+Gas Station | Petrol+Person A+++File: hledger.info,  Node: diff,  Next: files,  Prev: descriptions,  Up: COMMANDS++11.14 diff+==========++diff+Compares a particular account's transactions in two input files.  It+shows any transactions to this account which are in one file but not in+the other.++   More precisely, for each posting affecting this account in either+file, it looks for a corresponding posting in the other file which posts+the same amount to the same account (ignoring date, description, etc.)+Since postings not transactions are compared, this also works when+multiple bank transactions have been combined into a single journal+entry.++   This is useful eg if you have downloaded an account's transactions+from your bank (eg as CSV data).  When hledger and your bank disagree+about the account balance, you can compare the bank data with your+journal to find out the cause.++   Examples:++$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro +These transactions are in the first file only:++2014/01/01 Opening Balances+    assets:bank:giro              EUR ...+    ...+    equity:opening balances       EUR -...++These transactions are in the second file only:+++File: hledger.info,  Node: files,  Next: help,  Prev: diff,  Up: COMMANDS++11.15 files+===========++files+List all files included in the journal.  With a REGEX argument, only+file names matching the regular expression (case sensitive) are shown.+++File: hledger.info,  Node: help,  Next: import,  Prev: files,  Up: COMMANDS++11.16 help+==========++help+Show the hledger user manual in one of several formats, optionally+positioned at a given TOPIC (if possible).++   TOPIC is any heading in the manual, or the start of any heading (but+not the middle).  It is case insensitive.++   Some examples: 'commands', 'print', 'forecast', '"auto postings"',+'"commodity column"'.++   This command shows the user manual built in to this hledger version.+It can be useful if the correct version of the hledger manual, or the+usual viewing tools, are not installed on your system.++   By default it uses the best viewer it can find in $PATH, in this+order: 'info', 'man', $PAGER (unless a topic is specified), 'less', or+stdout.  When run non-interactively, it always uses stdout.  Or you can+select a particular viewer with the '-i' (info), '-m' (man), or '-p'+(pager) flags.+++File: hledger.info,  Node: import,  Next: incomestatement,  Prev: help,  Up: COMMANDS++11.17 import+============++import+Read new transactions added to each FILE since last run, and add them to+the main journal file.  Or with -dry-run, just print the transactions+that would be added.  Or with -catchup, just mark all of the FILEs'+transactions as imported, without actually importing any.++   Unlike other hledger commands, with 'import' the journal file is an+output file, and will be modified, though only by appending (existing+data will not be changed).  The input files are specified as arguments,+so to import one or more CSV files to your main journal, you will run+'hledger import bank.csv' or perhaps 'hledger import *.csv'.++   Note you can import from any file format, though CSV files are the+most common import source, and these docs focus on that case.++* Menu:++* Deduplication::+* Import testing::+* Importing balance assignments::+* Commodity display styles::+++File: hledger.info,  Node: Deduplication,  Next: Import testing,  Up: import++11.17.1 Deduplication+---------------------++As a convenience 'import' does _deduplication_ while reading+transactions.  This does not mean "ignore transactions that look the+same", but rather "ignore transactions that have been seen before".+This is intended for when you are periodically importing foreign data+which may contain already-imported transactions.  So eg, if every day+you download bank CSV files containing redundant data, you can safely+run 'hledger import bank.csv' and only new transactions will be+imported.  ('import' is idempotent.)++   Since the items being read (CSV records, eg) often do not come with+unique identifiers, hledger detects new transactions by date, assuming+that:++  1. new items always have the newest dates+  2. item dates do not change across reads+  3. and items with the same date remain in the same relative order+     across reads.++   These are often true of CSV files representing transactions, or true+enough so that it works pretty well in practice.  1 is important, but+violations of 2 and 3 amongst the old transactions won't matter (and if+you import often, the new transactions will be few, so less likely to be+the ones affected).++   hledger remembers the latest date processed in each input file by+saving a hidden ".latest" state file in the same directory.  Eg when+reading 'finance/bank.csv', it will look for and update the+'finance/.latest.bank.csv' state file.  The format is simple: one or+more lines containing the same ISO-format date (YYYY-MM-DD), meaning "I+have processed transactions up to this date, and this many of them on+that date."  Normally you won't see or manipulate these state files+yourself.  But if needed, you can delete them to reset the state (making+all transactions "new"), or you can construct them to "catch up" to a+certain date.++   Note deduplication (and updating of state files) can also be done by+'print --new', but this is less often used.+++File: hledger.info,  Node: Import testing,  Next: Importing balance assignments,  Prev: Deduplication,  Up: import++11.17.2 Import testing+----------------------++With '--dry-run', the transactions that will be imported are printed to+the terminal, without updating your journal or state files.  The output+is valid journal format, like the print command, so you can re-parse it.+Eg, to see any importable transactions which CSV rules have not+categorised:++$ hledger import --dry bank.csv | hledger -f- -I print unknown++   or (live updating):++$ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown'+++File: hledger.info,  Node: Importing balance assignments,  Next: Commodity display styles,  Prev: Import testing,  Up: import++11.17.3 Importing balance assignments+-------------------------------------++Entries added by import will have their posting amounts made explicit+(like 'hledger print -x').  This means that any balance assignments in+imported files must be evaluated; but, imported files don't get to see+the main file's account balances.  As a result, importing entries with+balance assignments (eg from an institution that provides only balances+and not posting amounts) will probably generate incorrect posting+amounts.  To avoid this problem, use print instead of import:++$ hledger print IMPORTFILE [--new] >> $LEDGER_FILE++   (If you think import should leave amounts implicit like print does,+please test it and send a pull request.)+++File: hledger.info,  Node: Commodity display styles,  Prev: Importing balance assignments,  Up: import++11.17.4 Commodity display styles+--------------------------------++Imported amounts will be formatted according to the canonical commodity+styles (declared or inferred) in the main journal file.+++File: hledger.info,  Node: incomestatement,  Next: notes,  Prev: import,  Up: COMMANDS++11.18 incomestatement+=====================++incomestatement, is++   This command displays an income statement, showing revenues and+expenses during one or more periods.  Amounts are shown with normal+positive sign, as in conventional financial statements.++   The revenue and expense accounts shown are those accounts declared+with the 'Revenue' or 'Expense' type, or otherwise all accounts under a+top-level 'revenue' or 'income' or 'expense' account (case insensitive,+plurals allowed).++   Example:++$ hledger incomestatement+Income Statement++Revenues:+                 $-2  income+                 $-1    gifts+                 $-1    salary+--------------------+                 $-2++Expenses:+                  $2  expenses+                  $1    food+                  $1    supplies+--------------------+                  $2++Total:+--------------------+                   0++   This command is a higher-level variant of the 'balance' command, and+supports many of that command's features, such as multi-period reports.+It is similar to 'hledger balance '(revenues|income)' expenses', but+with smarter account detection, and revenues/income displayed with their+sign flipped.++   This command also supports the output destination and output format+options The output formats supported are 'txt', 'csv', 'html', and+(experimental) 'json'.+++File: hledger.info,  Node: notes,  Next: payees,  Prev: incomestatement,  Up: COMMANDS++11.19 notes+===========++notes+List the unique notes that appear in transactions.++   This command lists the unique notes that appear in transactions, in+alphabetic order.  You can add a query to select a subset of+transactions.  The note is the part of the transaction description after+a | character (or if there is no |, the whole description).++   Example:++$ hledger notes+Petrol+Snacks+++File: hledger.info,  Node: payees,  Next: prices,  Prev: notes,  Up: COMMANDS++11.20 payees+============++payees+List the unique payee/payer names that appear in transactions.++   This command lists unique payee/payer names which have been declared+with payee directives (-declared), used in transaction descriptions+(-used), or both (the default).++   The payee/payer is the part of the transaction description before a |+character (or if there is no |, the whole description).++   You can add query arguments to select a subset of transactions.  This+implies -used.++   Example:++$ hledger payees+Store Name+Gas Station+Person A+++File: hledger.info,  Node: prices,  Next: print,  Prev: payees,  Up: COMMANDS++11.21 prices+============++prices+Print market price directives from the journal.  With+-infer-market-prices, generate additional market prices from transaction+prices.  With -infer-reverse-prices, also generate market prices by+inverting transaction prices.  Prices (and postings providing+transaction prices) can be filtered by a query.  Price amounts are+displayed with their full precision.+++File: hledger.info,  Node: print,  Next: print-unique,  Prev: prices,  Up: COMMANDS++11.22 print+===========++print+Show transaction journal entries, sorted by date.++   The print command displays full journal entries (transactions) from+the journal file, sorted by date (or with '--date2', by secondary date).++   Amounts are shown mostly normalised to commodity display style, eg+the placement of commodity symbols will be consistent.  All of their+decimal places are shown, as in the original journal entry (with one+alteration: in some cases trailing zeroes are added.)++   Amounts are shown right-aligned within each transaction (but not+across all transactions).++   Directives and inter-transaction comments are not shown, currently.+This means the print command is somewhat lossy, and if you are using it+to reformat your journal you should take care to also copy over the+directives and file-level comments.++   Eg:++$ hledger print+2008/01/01 income+    assets:bank:checking            $1+    income:salary                  $-1++2008/06/01 gift+    assets:bank:checking            $1+    income:gifts                   $-1++2008/06/02 save+    assets:bank:saving              $1+    assets:bank:checking           $-1++2008/06/03 * eat & shop+    expenses:food                $1+    expenses:supplies            $1+    assets:cash                 $-2++2008/12/31 * pay off+    liabilities:debts               $1+    assets:bank:checking           $-1++   print's output is usually a valid hledger journal, and you can+process it again with a second hledger command.  This can be useful for+certain kinds of search, eg:++# Show running total of food expenses paid from cash.+# -f- reads from stdin. -I/--ignore-assertions is sometimes needed.+$ hledger print assets:cash | hledger -f- -I reg expenses:food++   There are some situations where print's output can become+unparseable:++   * Valuation affects posting amounts but not balance assertion or+     balance assignment amounts, potentially causing those to fail.+   * Auto postings can generate postings with too many missing amounts.+   * Account aliases can generate bad account names.++   Normally, the journal entry's explicit or implicit amount style is+preserved.  For example, when an amount is omitted in the journal, it+will not appear in the output.  Similarly, when a transaction price is+implied but not written, it will not appear in the output.  You can use+the '-x'/'--explicit' flag to make all amounts and transaction prices+explicit, which can be useful for troubleshooting or for making your+journal more readable and robust against data entry errors.  '-x' is+also implied by using any of '-B','-V','-X','--value'.++   Note, '-x'/'--explicit' will cause postings with a multi-commodity+amount (these can arise when a multi-commodity transaction has an+implicit amount) to be split into multiple single-commodity postings,+keeping the output parseable.++   With '-B'/'--cost', amounts with transaction prices are converted to+cost using that price.  This can be used for troubleshooting.++   With '-m'/'--match' and a STR argument, print will show at most one+transaction: the one one whose description is most similar to STR, and+is most recent.  STR should contain at least two characters.  If there+is no similar-enough match, no transaction will be shown.++   With '--new', hledger prints only transactions it has not seen on a+previous run.  This uses the same deduplication system as the 'import'+command.  (See import's docs for details.)++   This command also supports the output destination and output format+options The output formats supported are 'txt', 'csv', and+(experimental) 'json' and 'sql'.++   Here's an example of print's CSV output:++$ hledger print -Ocsv+"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment"+"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","",""+"1","2008/01/01","","","","income","","income:salary","-1","$","1","","",""+"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","",""+"2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","",""+"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","",""+"3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","",""+"4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","",""+"4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","",""+"4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","",""+"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""+"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""++   * There is one CSV record per posting, with the parent transaction's+     fields repeated.+   * The "txnidx" (transaction index) field shows which postings belong+     to the same transaction.  (This number might change if transactions+     are reordered within the file, files are parsed/included in a+     different order, etc.)+   * The amount is separated into "commodity" (the symbol) and "amount"+     (numeric quantity) fields.+   * The numeric amount is repeated in either the "credit" or "debit"+     column, for convenience.  (Those names are not accurate in the+     accounting sense; it just puts negative amounts under credit and+     zero or greater amounts under debit.)+++File: hledger.info,  Node: print-unique,  Next: register,  Prev: print,  Up: COMMANDS++11.23 print-unique+==================++print-unique+Print transactions which do not reuse an already-seen description.++   Example:++$ cat unique.journal+1/1 test+ (acct:one)  1+2/2 test+ (acct:two)  2+$ LEDGER_FILE=unique.journal hledger print-unique+(-f option not supported)+2015/01/01 test+    (acct:one)             1+++File: hledger.info,  Node: register,  Next: register-match,  Prev: print-unique,  Up: COMMANDS++11.24 register+==============++register, reg+Show postings and their running total.++   The register command displays matched postings, across all accounts,+in date order, with their running total or running historical balance.+(See also the 'aregister' command, which shows matched transactions in a+specific account.)++   register normally shows line per posting, but note that+multi-commodity amounts will occupy multiple lines (one line per+commodity).++   It is typically used with a query selecting a particular account, to+see that account's activity:++$ hledger register checking+2008/01/01 income               assets:bank:checking            $1           $1+2008/06/01 gift                 assets:bank:checking            $1           $2+2008/06/02 save                 assets:bank:checking           $-1           $1+2008/12/31 pay off              assets:bank:checking           $-1            0++   With -date2, it shows and sorts by secondary date instead.++   The '--historical'/'-H' flag adds the balance from any undisplayed+prior postings to the running total.  This is useful when you want to+see only recent activity, with a historically accurate running balance:++$ hledger register checking -b 2008/6 --historical+2008/06/01 gift                 assets:bank:checking            $1           $2+2008/06/02 save                 assets:bank:checking           $-1           $1+2008/12/31 pay off              assets:bank:checking           $-1            0++   The '--depth' option limits the amount of sub-account detail+displayed.++   The '--average'/'-A' flag shows the running average posting amount+instead of the running total (so, the final number displayed is the+average for the whole report period).  This flag implies '--empty' (see+below).  It is affected by '--historical'.  It works best when showing+just one account and one commodity.++   The '--related'/'-r' flag shows the _other_ postings in the+transactions of the postings which would normally be shown.++   The '--invert' flag negates all amounts.  For example, it can be used+on an income account where amounts are normally displayed as negative+numbers.  It's also useful to show postings on the checking account+together with the related account:++$ hledger register --related --invert assets:checking++   With a reporting interval, register shows summary postings, one per+interval, aggregating the postings to each account:++$ hledger register --monthly income+2008/01                 income:salary                          $-1          $-1+2008/06                 income:gifts                           $-1          $-2++   Periods with no activity, and summary postings with a zero amount,+are not shown by default; use the '--empty'/'-E' flag to see them:++$ hledger register --monthly income -E+2008/01                 income:salary                          $-1          $-1+2008/02                                                          0          $-1+2008/03                                                          0          $-1+2008/04                                                          0          $-1+2008/05                                                          0          $-1+2008/06                 income:gifts                           $-1          $-2+2008/07                                                          0          $-2+2008/08                                                          0          $-2+2008/09                                                          0          $-2+2008/10                                                          0          $-2+2008/11                                                          0          $-2+2008/12                                                          0          $-2++   Often, you'll want to see just one line per interval.  The '--depth'+option helps with this, causing subaccounts to be aggregated:++$ hledger register --monthly assets --depth 1h+2008/01                 assets                                  $1           $1+2008/06                 assets                                 $-1            0+2008/12                 assets                                 $-1          $-1++   Note when using report intervals, if you specify start/end dates+these will be adjusted outward if necessary to contain a whole number of+intervals.  This ensures that the first and last intervals are full+length and comparable to the others in the report.++* Menu:++* Custom register output::+++File: hledger.info,  Node: Custom register output,  Up: register++11.24.1 Custom register output+------------------------------++register uses the full terminal width by default, except on windows.+You can override this by setting the 'COLUMNS' environment variable (not+a bash shell variable) or by using the '--width'/'-w' option.++   The description and account columns normally share the space equally+(about half of (width - 40) each).  You can adjust this by adding a+description width as part of -width's argument, comma-separated:+'--width W,D' .  Here's a diagram (won't display correctly in -help):++<--------------------------------- width (W) ---------------------------------->+date (10)  description (D)       account (W-41-D)     amount (12)   balance (12)+DDDDDDDDDD dddddddddddddddddddd  aaaaaaaaaaaaaaaaaaa  AAAAAAAAAAAA  AAAAAAAAAAAA++   and some examples:++$ hledger reg                     # use terminal width (or 80 on windows)+$ hledger reg -w 100              # use width 100+$ COLUMNS=100 hledger reg         # set with one-time environment variable+$ export COLUMNS=100; hledger reg # set till session end (or window resize)+$ hledger reg -w 100,40           # set overall width 100, description width 40+$ hledger reg -w $COLUMNS,40      # use terminal width, & description width 40++   This command also supports the output destination and output format+options The output formats supported are 'txt', 'csv', and+(experimental) 'json'.+++File: hledger.info,  Node: register-match,  Next: rewrite,  Prev: register,  Up: COMMANDS++11.25 register-match+====================++register-match+Print the one posting whose transaction description is closest to DESC,+in the style of the register command.  If there are multiple equally+good matches, it shows the most recent.  Query options (options, not+arguments) can be used to restrict the search space.  Helps+ledger-autosync detect already-seen transactions when importing.+++File: hledger.info,  Node: rewrite,  Next: roi,  Prev: register-match,  Up: COMMANDS++11.26 rewrite+=============++rewrite+Print all transactions, rewriting the postings of matched transactions.+For now the only rewrite available is adding new postings, like print+-auto.++   This is a start at a generic rewriter of transaction entries.  It+reads the default journal and prints the transactions, like print, but+adds one or more specified postings to any transactions matching QUERY.+The posting amounts can be fixed, or a multiplier of the existing+transaction's first posting amount.++   Examples:++$ hledger-rewrite.hs ^income --add-posting '(liabilities:tax)  *.33  ; income tax' --add-posting '(reserve:gifts)  $100'+$ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts)  *-1"'+$ hledger-rewrite.hs -f rewrites.hledger++   rewrites.hledger may consist of entries like:++= ^income amt:<0 date:2017+  (liabilities:tax)  *0.33  ; tax on income+  (reserve:grocery)  *0.25  ; reserve 25% for grocery+  (reserve:)  *0.25  ; reserve 25% for grocery++   Note the single quotes to protect the dollar sign from bash, and the+two spaces between account and amount.++   More:++$ hledger rewrite -- [QUERY]        --add-posting "ACCT  AMTEXPR" ...+$ hledger rewrite -- ^income        --add-posting '(liabilities:tax)  *.33'+$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts)  *-1"'+$ hledger rewrite -- ^income        --add-posting '(budget:foreign currency)  *0.25 JPY; diversify'++   Argument for '--add-posting' option is a usual posting of transaction+with an exception for amount specification.  More precisely, you can use+''*'' (star symbol) before the amount to indicate that that this is a+factor for an amount of original matched posting.  If the amount+includes a commodity name, the new posting amount will be in the new+commodity; otherwise, it will be in the matched posting amount's+commodity.++* Menu:++* Re-write rules in a file::+* Diff output format::+* rewrite vs print --auto::+++File: hledger.info,  Node: Re-write rules in a file,  Next: Diff output format,  Up: rewrite++11.26.1 Re-write rules in a file+--------------------------------++During the run this tool will execute so called "Automated Transactions"+found in any journal it process.  I.e instead of specifying this+operations in command line you can put them in a journal file.++$ rewrite-rules.journal++   Make contents look like this:++= ^income+    (liabilities:tax)  *.33++= expenses:gifts+    budget:gifts  *-1+    assets:budget  *1++   Note that ''='' (equality symbol) that is used instead of date in+transactions you usually write.  It indicates the query by which you+want to match the posting to add new ones.++$ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal++   This is something similar to the commands pipeline:++$ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax)  *.33' \+  | hledger rewrite -- -f - expenses:gifts      --add-posting 'budget:gifts  *-1'       \+                                                --add-posting 'assets:budget  *1'       \+  > rewritten-tidy-output.journal++   It is important to understand that relative order of such entries in+journal is important.  You can re-use result of previously added+postings.+++File: hledger.info,  Node: Diff output format,  Next: rewrite vs print --auto,  Prev: Re-write rules in a file,  Up: rewrite++11.26.2 Diff output format+--------------------------++To use this tool for batch modification of your journal files you may+find useful output in form of unified diff.++$ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax)  *.33'++   Output might look like:++--- /tmp/examples/sample.journal++++ /tmp/examples/sample.journal+@@ -18,3 +18,4 @@+ 2008/01/01 income+-    assets:bank:checking  $1++    assets:bank:checking            $1+     income:salary++    (liabilities:tax)                0+@@ -22,3 +23,4 @@+ 2008/06/01 gift+-    assets:bank:checking  $1++    assets:bank:checking            $1+     income:gifts++    (liabilities:tax)                0++   If you'll pass this through 'patch' tool you'll get transactions+containing the posting that matches your query be updated.  Note that+multiple files might be update according to list of input files+specified via '--file' options and 'include' directives inside of these+files.++   Be careful.  Whole transaction being re-formatted in a style of+output from 'hledger print'.++   See also:++   https://github.com/simonmichael/hledger/issues/99+++File: hledger.info,  Node: rewrite vs print --auto,  Prev: Diff output format,  Up: rewrite++11.26.3 rewrite vs. print -auto+-------------------------------++This command predates print -auto, and currently does much the same+thing, but with these differences:++   * with multiple files, rewrite lets rules in any file affect all+     other files.  print -auto uses standard directive scoping; rules+     affect only child files.++   * rewrite's query limits which transactions can be rewritten; all are+     printed.  print -auto's query limits which transactions are+     printed.++   * rewrite applies rules specified on command line or in the journal.+     print -auto applies rules specified in the journal.+++File: hledger.info,  Node: roi,  Next: stats,  Prev: rewrite,  Up: COMMANDS++11.27 roi+=========++roi+Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on+your investments.++   At a minimum, you need to supply a query (which could be just an+account name) to select your investment(s) with '--inv', and another+query to identify your profit and loss transactions with '--pnl'.++   If you do not record changes in the value of your investment+manually, or do not require computation of time-weighted return (TWR),+'--pnl' could be an empty query ('--pnl ""' or '--pnl STR' where 'STR'+does not match any of your accounts).++   This command will compute and display the internalized rate of return+(IRR) and time-weighted rate of return (TWR) for your investments for+the time period requested.  Both rates of return are annualized before+display, regardless of the length of reporting interval.++   Price directives will be taken into account if you supply appropriate+'--cost' or '--value' flags (see VALUATION).++   Note, in some cases this report can fail, for these reasons:++   * Error (NotBracketed): No solution for Internal Rate of Return+     (IRR). Possible causes: IRR is huge (>1000000%), balance of+     investment becomes negative at some point in time.+   * Error (SearchFailed): Failed to find solution for Internal Rate of+     Return (IRR). Either search does not converge to a solution, or+     converges too slowly.++   Examples:++   * Using roi to compute total return of investment in stocks:+     https://github.com/simonmichael/hledger/blob/master/examples/investing/roi-unrealised.ledger++   * Cookbook > Return on Investment: https://hledger.org/roi.html++* Menu:++* Spaces and special characters in --inv and --pnl::+* Semantics of --inv and --pnl::+* IRR and TWR explained::+++File: hledger.info,  Node: Spaces and special characters in --inv and --pnl,  Next: Semantics of --inv and --pnl,  Up: roi++11.27.1 Spaces and special characters in '--inv' and+----------------------------------------------------++'--pnl' Note that '--inv' and '--pnl''s argument is a query, and queries+could have several space-separated terms (see QUERIES).++   To indicate that all search terms form single command-line argument,+you will need to put them in quotes (see Special characters):++$ hledger roi --inv 'term1 term2 term3 ...'++   If any query terms contain spaces themselves, you will need an extra+level of nested quoting, eg:++$ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'"+++File: hledger.info,  Node: Semantics of --inv and --pnl,  Next: IRR and TWR explained,  Prev: Spaces and special characters in --inv and --pnl,  Up: roi++11.27.2 Semantics of '--inv' and '--pnl'+----------------------------------------++Query supplied to '--inv' has to match all transactions that are related+to your investment.  Transactions not matching '--inv' will be ignored.++   In these transactions, ROI will conside postings that match '--inv'+to be "investment postings" and other postings (not matching '--inv')+will be sorted into two categories: "cash flow" and "profit and loss",+as ROI needs to know which part of the investment value is your+contributions and which is due to the return on investment.++   * "Cash flow" is depositing or withdrawing money, buying or selling+     assets, or otherwise converting between your investment commodity+     and any other commodity.  Example:++     2019-01-01 Investing in Snake Oil+       assets:cash          -$100+       investment:snake oil+     +     2020-01-01 Selling my Snake Oil+       assets:cash           $10+       investment:snake oil  = 0++   * "Profit and loss" is change in the value of your investment:++     2019-06-01 Snake Oil falls in value+       investment:snake oil  = $57+       equity:unrealized profit or loss++   All non-investment postings are assumed to be "cash flow", unless+they match '--pnl' query.  Changes in value of your investment due to+"profit and loss" postings will be considered as part of your investment+return.++   Example: if you use '--inv snake --pnl equity:unrealized', then+postings in the example below would be classifed as:++2019-01-01 Snake Oil #1+  assets:cash          -$100   ; cash flow posting+  investment:snake oil         ; investment posting++2019-03-01 Snake Oil #2+  equity:unrealized pnl  -$100 ; profit and loss posting+  snake oil                    ; investment posting++2019-07-01 Snake Oil #3+  equity:unrealized pnl        ; profit and loss posting+  cash          -$100          ; cash flow posting+  snake oil     $50            ; investment posting+++File: hledger.info,  Node: IRR and TWR explained,  Prev: Semantics of --inv and --pnl,  Up: roi++11.27.3 IRR and TWR explained+-----------------------------++"ROI" stands for "return on investment".  Traditionally this was+computed as a difference between current value of investment and its+initial value, expressed in percentage of the initial value.++   However, this approach is only practical in simple cases, where+investments receives no in-flows or out-flows of money, and where rate+of growth is fixed over time.  For more complex scenarios you need+different ways to compute rate of return, and this command implements+two of them: IRR and TWR.++   Internal rate of return, or "IRR" (also called "money-weighted rate+of return") takes into account effects of in-flows and out-flows.+Naively, if you are withdrawing from your investment, your future gains+would be smaller (in absolute numbers), and will be a smaller percentage+of your initial investment, and if you are adding to your investment,+you will receive bigger absolute gains (but probably at the same rate of+return).  IRR is a way to compute rate of return for each period between+in-flow or out-flow of money, and then combine them in a way that gives+you a compound annual rate of return that investment is expected to+generate.++   As mentioned before, in-flows and out-flows would be any cash that+you personally put in or withdraw, and for the "roi" command, these are+the postings that match the query in the'--inv' argument and NOT match+the query in the'--pnl' argument.++   If you manually record changes in the value of your investment as+transactions that balance them against "profit and loss" (or "unrealized+gains") account or use price directives, then in order for IRR to+compute the precise effect of your in-flows and out-flows on the rate of+return, you will need to record the value of your investement on or+close to the days when in- or out-flows occur.++   In technical terms, IRR uses the same approach as computation of net+present value, and tries to find a discount rate that makes net present+value of all the cash flows of your investment to add up to zero.  This+could be hard to wrap your head around, especially if you haven't done+discounted cash flow analysis before.  Implementation of IRR in hledger+should produce results that match the 'XIRR' formula in Excel.++   Second way to compute rate of return that 'roi' command implements is+called "time-weighted rate of return" or "TWR". Like IRR, it will also+break the history of your investment into periods between in-flows,+out-flows and value changes, to compute rate of return per each period+and then a compound rate of return.  However, internal workings of TWR+are quite different.++   TWR represents your investment as an imaginary "unit fund" where+in-flows/ out-flows lead to buying or selling "units" of your investment+and changes in its value change the value of "investment unit".  Change+in "unit price" over the reporting period gives you rate of return of+your investment.++   References:++   * Explanation of rate of return+   * Explanation of IRR+   * Explanation of TWR+   * Examples of computing IRR and TWR and discussion of the limitations+     of both metrics+++File: hledger.info,  Node: stats,  Next: tags,  Prev: roi,  Up: COMMANDS++11.28 stats+===========++stats+Show journal and performance statistics.++   The stats command displays summary information for the whole journal,+or a matched part of it.  With a reporting interval, it shows a report+for each report period.++   At the end, it shows (in the terminal) the overall run time and+number of transactions processed per second.  Note these are approximate+and will vary based on machine, current load, data size, hledger+version, haskell lib versions, GHC version..  but they may be of+interest.  The 'stats' command's run time is similar to that of a+single-column balance report.++   Example:++$ hledger stats -f examples/1000x1000x10.journal+Main file                : /Users/simon/src/hledger/examples/1000x1000x10.journal+Included files           : +Transactions span        : 2000-01-01 to 2002-09-27 (1000 days)+Last transaction         : 2002-09-26 (6995 days ago)+Transactions             : 1000 (1.0 per day)+Transactions last 30 days: 0 (0.0 per day)+Transactions last 7 days : 0 (0.0 per day)+Payees/descriptions      : 1000+Accounts                 : 1000 (depth 10)+Commodities              : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z)+Market prices            : 1000 (A)++Run time                 : 0.12 s+Throughput               : 8342 txns/s++   This command also supports output destination and output format+selection.+++File: hledger.info,  Node: tags,  Next: test,  Prev: stats,  Up: COMMANDS++11.29 tags+==========++tags+List the unique tag names used in the journal.  With a TAGREGEX+argument, only tag names matching the regular expression (case+insensitive) are shown.  With QUERY arguments, only transactions+matching the query are considered.++   With the -values flag, the tags' unique values are listed instead.++   With -parsed flag, all tags or values are shown in the order they are+parsed from the input data, including duplicates.++   With -E/-empty, any blank/empty values will also be shown, otherwise+they are omitted.+++File: hledger.info,  Node: test,  Next: About add-on commands,  Prev: tags,  Up: COMMANDS++11.30 test+==========++test+Run built-in unit tests.++   This command runs the unit tests built in to hledger and hledger-lib,+printing the results on stdout.  If any test fails, the exit code will+be non-zero.++   This is mainly used by hledger developers, but you can also use it to+sanity-check the installed hledger executable on your platform.  All+tests are expected to pass - if you ever see a failure, please report as+a bug!++   This command also accepts tasty test runner options, written after a+- (double hyphen).  Eg to run only the tests in Hledger.Data.Amount,+with ANSI colour codes disabled:++$ hledger test -- -pData.Amount --color=never++   For help on these, see https://github.com/feuerbach/tasty#options+('-- --help' currently doesn't show them).+++File: hledger.info,  Node: About add-on commands,  Prev: test,  Up: COMMANDS++11.31 About add-on commands+===========================++Add-on commands are programs or scripts in your PATH++   * whose name starts with 'hledger-'+   * whose name ends with a recognised file extension:+     '.bat','.com','.exe', '.hs','.lhs','.pl','.py','.rb','.rkt','.sh'+     or none+   * and (on unix, mac) which are executable by the current user.++   Add-ons are a relatively easy way to add local features or experiment+with new ideas.  They can be written in any language, but haskell+scripts have a big advantage: they can use the same hledger library+functions that built-in commands use for command-line options, parsing+and reporting.  Some experimental/example add-on scripts can be found in+the hledger repo's bin/ directory.++   Note in a hledger command line, add-on command flags must have a+double dash ('--') preceding them.  Eg you must write:++$ hledger web -- --serve++   and not:++$ hledger web --serve++   (because the '--serve' flag belongs to 'hledger-web', not 'hledger').++   The '-h/--help' and '--version' flags don't require '--'.++   If you have any trouble with this, remember you can always run the+add-on program directly, eg:++$ hledger-web --serve+++File: hledger.info,  Node: JOURNAL FORMAT,  Next: CSV FORMAT,  Prev: COMMANDS,  Up: Top++12 JOURNAL FORMAT+*****************++hledger's default file format, representing a General Journal.++   hledger's usual data source is a plain text file containing journal+entries in hledger journal format.  This file represents a standard+accounting general journal.  I use file names ending in '.journal', but+that's not required.  The journal file contains a number of transaction+entries, each describing a transfer of money (or any commodity) between+two or more named accounts, in a simple format readable by both hledger+and humans.++   hledger's journal format is a compatible subset, mostly, of ledger's+journal format, so hledger can work with compatible ledger journal files+as well.  It's safe, and encouraged, to run both hledger and ledger on+the same journal file, eg to validate the results you're getting.++   You can use hledger without learning any more about this file; just+use the add or web or import commands to create and update it.++   Many users, though, edit the journal file with a text editor, and+track changes with a version control system such as git.  Editor addons+such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and+hledger-vscode for Visual Studio Code, make this easier, adding colour,+formatting, tab completion, and useful commands.  See Editor+configuration at hledger.org for the full list.++   Here's a description of each part of the file format (and hledger's+data model).  These are mostly in the order you'll use them, but in some+cases related concepts have been grouped together for easy reference, or+linked before they are introduced, so feel free to skip over anything+that looks unnecessary right now.++* Menu:++* Transactions::+* Dates::+* Status::+* Code::+* Description::+* Comments::+* Tags::+* Postings::+* Account names::+* Amounts::+* Transaction prices::+* Lot prices lot dates::+* Balance assertions::+* Balance assignments::+* Directives::+* Directives and multiple files::+* Comment blocks::+* Including other files::+* Default year::+* Declaring payees::+* Declaring the decimal mark::+* Declaring commodities::+* Default commodity::+* Declaring market prices::+* Declaring accounts::+* Rewriting accounts::+* Default parent account::+* Periodic transactions::+* Auto postings::+++File: hledger.info,  Node: Transactions,  Next: Dates,  Up: JOURNAL FORMAT++12.1 Transactions+=================++Transactions are the main unit of information in a journal file.  They+represent events, typically a movement of some quantity of commodities+between two or more named accounts.++   Each transaction is recorded as a journal entry, beginning with a+simple date in column 0.  This can be followed by any of the following+optional fields, separated by spaces:++   * a status character (empty, '!', or '*')+   * a code (any short number or text, enclosed in parentheses)+   * a description (any remaining text until end of line or a semicolon)+   * a comment (any remaining text following a semicolon until end of+     line, and any following indented lines beginning with a semicolon)+   * 0 or more indented _posting_ lines, describing what was transferred+     and the accounts involved (indented comment lines are also allowed,+     but not blank lines or non-indented lines).++   Here's a simple journal file containing one transaction:++2008/01/01 income+  assets:bank:checking   $1+  income:salary         $-1+++File: hledger.info,  Node: Dates,  Next: Status,  Prev: Transactions,  Up: JOURNAL FORMAT++12.2 Dates+==========++* Menu:++* Simple dates::+* Secondary dates::+* Posting dates::+++File: hledger.info,  Node: Simple dates,  Next: Secondary dates,  Up: Dates++12.2.1 Simple dates+-------------------++Dates in the journal file use _simple dates_ format: 'YYYY-MM-DD' or+'YYYY/MM/DD' or 'YYYY.MM.DD', with leading zeros optional.  The year may+be omitted, in which case it will be inferred from the context: the+current transaction, the default year set with a default year directive,+or the current date when the command is run.  Some examples:+'2010-01-31', '2010/01/31', '2010.1.31', '1/31'.++   (The UI also accepts simple dates, as well as the more flexible smart+dates documented in the hledger manual.)+++File: hledger.info,  Node: Secondary dates,  Next: Posting dates,  Prev: Simple dates,  Up: Dates++12.2.2 Secondary dates+----------------------++Real-life transactions sometimes involve more than one date - eg the+date you write a cheque, and the date it clears in your bank.  When you+want to model this, for more accurate daily balances, you can specify+individual posting dates.++   Or, you can use the older _secondary date_ feature (Ledger calls it+auxiliary date or effective date).  Note: we support this for+compatibility, but I usually recommend avoiding this feature; posting+dates are almost always clearer and simpler.++   A secondary date is written after the primary date, following an+equals sign.  If the year is omitted, the primary date's year is+assumed.  When running reports, the primary (left) date is used by+default, but with the '--date2' flag (or '--aux-date' or '--effective'),+the secondary (right) date will be used instead.++   The meaning of secondary dates is up to you, but it's best to follow+a consistent rule.  Eg "primary = the bank's clearing date, secondary =+date the transaction was initiated, if different", as shown here:++2010/2/23=2/19 movie ticket+  expenses:cinema                   $10+  assets:checking++$ hledger register checking+2010-02-23 movie ticket         assets:checking                $-10         $-10++$ hledger register checking --date2+2010-02-19 movie ticket         assets:checking                $-10         $-10+++File: hledger.info,  Node: Posting dates,  Prev: Secondary dates,  Up: Dates++12.2.3 Posting dates+--------------------++You can give individual postings a different date from their parent+transaction, by adding a posting comment containing a tag (see below)+like 'date:DATE'.  This is probably the best way to control posting+dates precisely.  Eg in this example the expense should appear in May+reports, and the deduction from checking should be reported on 6/1 for+easy bank reconciliation:++2015/5/30+    expenses:food     $10  ; food purchased on saturday 5/30+    assets:checking        ; bank cleared it on monday, date:6/1++$ hledger -f t.j register food+2015-05-30                      expenses:food                  $10           $10++$ hledger -f t.j register checking+2015-06-01                      assets:checking               $-10          $-10++   DATE should be a simple date; if the year is not specified it will+use the year of the transaction's date.  You can set the secondary date+similarly, with 'date2:DATE2'.  The 'date:' or 'date2:' tags must have a+valid simple date value if they are present, eg a 'date:' tag with no+value is not allowed.++   Ledger's earlier, more compact bracketed date syntax is also+supported: '[DATE]', '[DATE=DATE2]' or '[=DATE2]'.  hledger will attempt+to parse any square-bracketed sequence of the '0123456789/-.='+characters in this way.  With this syntax, DATE infers its year from the+transaction and DATE2 infers its year from DATE.+++File: hledger.info,  Node: Status,  Next: Code,  Prev: Dates,  Up: JOURNAL FORMAT++12.3 Status+===========++Transactions, or individual postings within a transaction, can have a+status mark, which is a single character before the transaction+description or posting account name, separated from it by a space,+indicating one of three statuses:++mark  status+ +-----------------+      unmarked+'!'   pending+'*'   cleared++   When reporting, you can filter by status with the '-U/--unmarked',+'-P/--pending', and '-C/--cleared' flags; or the 'status:', 'status:!',+and 'status:*' queries; or the U, P, C keys in hledger-ui.++   Note, in Ledger and in older versions of hledger, the "unmarked"+state is called "uncleared".  As of hledger 1.3 we have renamed it to+unmarked for clarity.++   To replicate Ledger and old hledger's behaviour of also matching+pending, combine -U and -P.++   Status marks are optional, but can be helpful eg for reconciling with+real-world accounts.  Some editor modes provide highlighting and+shortcuts for working with status.  Eg in Emacs ledger-mode, you can+toggle transaction status with C-c C-e, or posting status with C-c C-c.++   What "uncleared", "pending", and "cleared" actually mean is up to+you.  Here's one suggestion:++status     meaning+--------------------------------------------------------------------------+uncleared  recorded but not yet reconciled; needs review+pending    tentatively reconciled (if needed, eg during a big+           reconciliation)+cleared    complete, reconciled as far as possible, and considered+           correct++   With this scheme, you would use '-PC' to see the current balance at+your bank, '-U' to see things which will probably hit your bank soon+(like uncashed checks), and no flags to see the most up-to-date state of+your finances.+++File: hledger.info,  Node: Code,  Next: Description,  Prev: Status,  Up: JOURNAL FORMAT++12.4 Code+=========++After the status mark, but before the description, you can optionally+write a transaction "code", enclosed in parentheses.  This is a good+place to record a check number, or some other important transaction id+or reference number.+++File: hledger.info,  Node: Description,  Next: Comments,  Prev: Code,  Up: JOURNAL FORMAT++12.5 Description+================++A transaction's description is the rest of the line following the date+and status mark (or until a comment begins).  Sometimes called the+"narration" in traditional bookkeeping, it can be used for whatever you+wish, or left blank.  Transaction descriptions can be queried, unlike+comments.++* Menu:++* Payee and note::+++File: hledger.info,  Node: Payee and note,  Up: Description++12.5.1 Payee and note+---------------------++You can optionally include a '|' (pipe) character in descriptions to+subdivide the description into separate fields for payee/payer name on+the left (up to the first '|') and an additional note field on the right+(after the first '|').  This may be worthwhile if you need to do more+precise querying and pivoting by payee or by note.+++File: hledger.info,  Node: Comments,  Next: Tags,  Prev: Description,  Up: JOURNAL FORMAT++12.6 Comments+=============++Lines in the journal beginning with a semicolon (';') or hash ('#') or+star ('*') are comments, and will be ignored.  (Star comments cause+org-mode nodes to be ignored, allowing emacs users to fold and navigate+their journals with org-mode or orgstruct-mode.)++   You can attach comments to a transaction by writing them after the+description and/or indented on the following lines (before the+postings).  Similarly, you can attach comments to an individual posting+by writing them after the amount and/or indented on the following lines.+Transaction and posting comments must begin with a semicolon (';').++   Some examples:++# a file comment+; another file comment+* also a file comment, useful in org/orgstruct mode++comment+A multiline file comment, which continues+until a line containing just "end comment"+(or end of file).+end comment++2012/5/14 something  ; a transaction comment+    ; the transaction comment, continued+    posting1  1  ; a comment for posting 1+    posting2+    ; a comment for posting 2+    ; another comment line for posting 2+; a file comment (because not indented)++   You can also comment larger regions of a file using 'comment' and+'end comment' directives.+++File: hledger.info,  Node: Tags,  Next: Postings,  Prev: Comments,  Up: JOURNAL FORMAT++12.7 Tags+=========++Tags are a way to add extra labels or labelled data to postings and+transactions, which you can then search or pivot on.++   A simple tag is a word (which may contain hyphens) followed by a full+colon, written inside a transaction or posting comment line:++2017/1/16 bought groceries  ; sometag:++   Tags can have a value, which is the text after the colon, up to the+next comma or end of line, with leading/trailing whitespace removed:++    expenses:food    $10 ; a-posting-tag: the tag value++   Note this means hledger's tag values can not contain commas or+newlines.  Ending at commas means you can write multiple short tags on+one line, comma separated:++    assets:checking  ; a comment containing tag1:, tag2: some value ...++   Here,++   * "'a comment containing'" is just comment text, not a tag+   * "'tag1'" is a tag with no value+   * "'tag2'" is another tag, whose value is "'some value ...'"++   Tags in a transaction comment affect the transaction and all of its+postings, while tags in a posting comment affect only that posting.  For+example, the following transaction has three tags ('A', 'TAG2',+'third-tag') and the posting has four (those plus 'posting-tag'):++1/1 a transaction  ; A:, TAG2:+    ; third-tag: a third transaction tag, <- with a value+    (a)  $1  ; posting-tag:++   Tags are like Ledger's metadata feature, except hledger's tag values+are simple strings.+++File: hledger.info,  Node: Postings,  Next: Account names,  Prev: Tags,  Up: JOURNAL FORMAT++12.8 Postings+=============++A posting is an addition of some amount to, or removal of some amount+from, an account.  Each posting line begins with at least one space or+tab (2 or 4 spaces is common), followed by:++   * (optional) a status character (empty, '!', or '*'), followed by a+     space+   * (required) an account name (any text, optionally containing *single+     spaces*, until end of line or a double space)+   * (optional) *two or more spaces* or tabs followed by an amount.++   Positive amounts are being added to the account, negative amounts are+being removed.++   The amounts within a transaction must always sum up to zero.  As a+convenience, one amount may be left blank; it will be inferred so as to+balance the transaction.++   Be sure to note the unusual two-space delimiter between account name+and amount.  This makes it easy to write account names containing+spaces.  But if you accidentally leave only one space (or tab) before+the amount, the amount will be considered part of the account name.++* Menu:++* Virtual postings::+++File: hledger.info,  Node: Virtual postings,  Up: Postings++12.8.1 Virtual postings+-----------------------++A posting with a parenthesised account name is called a _virtual+posting_ or _unbalanced posting_, which means it is exempt from the+usual rule that a transaction's postings must balance add up to zero.++   This is not part of double entry accounting, so you might choose to+avoid this feature.  Or you can use it sparingly for certain special+cases where it can be convenient.  Eg, you could set opening balances+without using a balancing equity account:++1/1 opening balances+  (assets:checking)   $1000+  (assets:savings)    $2000++   A posting with a bracketed account name is called a _balanced virtual+posting_.  The balanced virtual postings in a transaction must add up to+zero (separately from other postings).  Eg:++1/1 buy food with cash, update budget envelope subaccounts, & something else+  assets:cash                    $-10 ; <- these balance+  expenses:food                    $7 ; <-+  expenses:food                    $3 ; <-+  [assets:checking:budget:food]  $-10    ; <- and these balance+  [assets:checking:available]     $10    ; <-+  (something:else)                 $5       ; <- not required to balance++   Ordinary non-parenthesised, non-bracketed postings are called _real+postings_.  You can exclude virtual postings from reports with the+'-R/--real' flag or 'real:1' query.+++File: hledger.info,  Node: Account names,  Next: Amounts,  Prev: Postings,  Up: JOURNAL FORMAT++12.9 Account names+==================++Account names typically have several parts separated by a full colon,+from which hledger derives a hierarchical chart of accounts.  They can+be anything you like, but in finance there are traditionally five+top-level accounts: 'assets', 'liabilities', 'revenue', 'expenses', and+'equity'.++   Account names may contain single spaces, eg: 'assets:accounts+receivable'.  Because of this, they must always be followed by *two or+more spaces* (or newline).++   Account names can be aliased.+++File: hledger.info,  Node: Amounts,  Next: Transaction prices,  Prev: Account names,  Up: JOURNAL FORMAT++12.10 Amounts+=============++After the account name, there is usually an amount.  (Important: between+account name and amount, there must be *two or more spaces*.)++   hledger's amount format is flexible, supporting several international+formats.  Here are some examples.  Amounts have a number (the+"quantity"):++1++   ..and usually a currency symbol or commodity name (more on this+below), to the left or right of the quantity, with or without a+separating space:++$1+4000 AAPL+3 "green apples"++   Amounts can be preceded by a minus sign (or a plus sign, though plus+is the default), The sign can be written before or after a left-side+commodity symbol:++-$1+$-1++   One or more spaces between the sign and the number are acceptable+when parsing (but they won't be displayed in output):+++ $1+$-      1++   Scientific E notation is allowed:++1E-6+EUR 1E3++* Menu:++* Decimal marks digit group marks::+* Commodity::+* Directives influencing number parsing and display::+* Commodity display style::+* Rounding::+++File: hledger.info,  Node: Decimal marks digit group marks,  Next: Commodity,  Up: Amounts++12.10.1 Decimal marks, digit group marks+----------------------------------------++A _decimal mark_ can be written as a period or a comma:++1.23+1,23456780000009++   In the integer part of the quantity (left of the decimal mark),+groups of digits can optionally be separated by a _digit group mark_ - a+space, comma, or period (different from the decimal mark):++     $1,000,000.00+  EUR 2.000.000,00+INR 9,99,99,999.00+      1 000 000.9455++   Note, a number containing a single digit group mark and no decimal+mark is ambiguous.  Are these digit group marks or decimal marks ?++1,000+1.000++   If you don't tell it otherwise, hledger will assume both of the above+are decimal marks, parsing both numbers as 1.++   To prevent confusing parsing mistakes and undetected typos,+especially if your data contains digit group marks (eg, thousands+separators), we recommend explicitly declaring the decimal mark+character in each journal file, using a directive at the top of the+file.  The 'decimal-mark' directive is best, otherwise 'commodity'+directives will also work.  These are described detail below.+++File: hledger.info,  Node: Commodity,  Next: Directives influencing number parsing and display,  Prev: Decimal marks digit group marks,  Up: Amounts++12.10.2 Commodity+-----------------++Amounts in hledger have both a "quantity", which is a signed decimal+number, and a "commodity", which is a currency symbol, stock ticker, or+any word or phrase describing something you are tracking.++   If the commodity name contains non-letters (spaces, numbers, or+punctuation), you must always write it inside double quotes ('"green+apples"', '"ABC123"').++   If you write just a bare number, that too will have a commodity, with+name '""'; we call that the "no-symbol commodity".++   Actually, hledger combines these single-commodity amounts into more+powerful multi-commodity amounts, which are what it works with most of+the time.  A multi-commodity amount could be, eg: '1 USD, 2 EUR, 3.456+TSLA'.  In practice, you will only see multi-commodity amounts in+hledger's output; you can't write them directly in the journal file.++   (If you are writing scripts or working with hledger's internals,+these are the 'Amount' and 'MixedAmount' types.)+++File: hledger.info,  Node: Directives influencing number parsing and display,  Next: Commodity display style,  Prev: Commodity,  Up: Amounts++12.10.3 Directives influencing number parsing and display+---------------------------------------------------------++You can add 'decimal-mark' and 'commodity' directives to the journal, to+declare and control these things more explicitly and precisely.  These+are described below, in JOURNAL FORMAT -> Declaring commodities.  Here's+a quick example:++# the decimal mark character used by all amounts in this file (all commodities)+decimal-mark .++# display styles for the $, EUR, INR and no-symbol commodities:+commodity $1,000.00+commodity EUR 1.000,00+commodity INR 9,99,99,999.00+commodity 1 000 000.9455+++File: hledger.info,  Node: Commodity display style,  Next: Rounding,  Prev: Directives influencing number parsing and display,  Up: Amounts++12.10.4 Commodity display style+-------------------------------++For the amounts in each commodity, hledger chooses a consistent display+style to use in most reports.  (Exceptions: price amounts, and all+amounts displayed by the 'print' command, are displayed with all of+their decimal digits visible.)++   A commodity's display style is inferred as follows.++   First, if a default commodity is declared with 'D', this commodity+and its style is applied to any no-symbol amounts in the journal.++   Then each commodity's style is inferred from one of the following, in+order of preference:++   * The commodity directive for that commodity (including the no-symbol+     commodity), if any.+   * The amounts in that commodity seen in the journal's transactions.+     (Posting amounts only; prices and periodic or auto rules are+     ignored, currently.)+   * The built-in fallback style, which looks like this: '$1000.00'.+     (Symbol on the left, period decimal mark, two decimal places.)++   A style is inferred from journal amounts as follows:++   * Use the general style (decimal mark, symbol placement) of the first+     amount+   * Use the first-seen digit group style (digit group mark, digit group+     sizes), if any+   * Use the maximum number of decimal places of all.++   Transaction price amounts don't affect the commodity display style+directly, but occasionally they can do so indirectly (eg when a+posting's amount is inferred using a transaction price).  If you find+this causing problems, use a commodity directive to fix the display+style.++   To summarise: each commodity's amounts will be normalised to (a) the+style declared by a 'commodity' directive, or (b) the style of the first+posting amount in the journal, with the first-seen digit group style and+the maximum-seen number of decimal places.  So if your reports are+showing amounts in a way you don't like, eg with too many decimal+places, use a commodity directive.  Some examples:++# declare euro, dollar, bitcoin and no-symbol commodities and set their +# input number formats and output display styles:+commodity EUR 1.000,+commodity $1000.00+commodity 1000.00000000 BTC+commodity 1 000.++   The inferred commodity style can be overridden by supplying a command+line option.+++File: hledger.info,  Node: Rounding,  Prev: Commodity display style,  Up: Amounts++12.10.5 Rounding+----------------++Amounts are stored internally as decimal numbers with up to 255 decimal+places, and displayed with the number of decimal places specified by the+commodity display style.  Note, hledger uses banker's rounding: it+rounds to the nearest even number, eg 0.5 displayed with zero decimal+places is "0").  (Guaranteed since hledger 1.17.1; in older versions+this could vary if hledger was built with Decimal < 0.5.1.)+++File: hledger.info,  Node: Transaction prices,  Next: Lot prices lot dates,  Prev: Amounts,  Up: JOURNAL FORMAT++12.11 Transaction prices+========================++Within a transaction, you can note an amount's price in another+commodity.  This can be used to document the cost (in a purchase) or+selling price (in a sale).  For example, transaction prices are useful+to record purchases of a foreign currency.  Note transaction prices are+fixed at the time of the transaction, and do not change over time.  See+also market prices, which represent prevailing exchange rates on a+certain date.++   There are several ways to record a transaction price:++  1. Write the price per unit, as '@ UNITPRICE' after the amount:++     2009/1/1+       assets:euros     €100 @ $1.35  ; one hundred euros purchased at $1.35 each+       assets:dollars                 ; balancing amount is -$135.00++  2. Write the total price, as '@@ TOTALPRICE' after the amount:++     2009/1/1+       assets:euros     €100 @@ $135  ; one hundred euros purchased at $135 for the lot+       assets:dollars++  3. Specify amounts for all postings, using exactly two commodities,+     and let hledger infer the price that balances the transaction:++     2009/1/1+       assets:euros     €100          ; one hundred euros purchased+       assets:dollars  $-135          ; for $135++  4. Like 1, but the '@' is parenthesised, i.e.  '(@)'; this is for+     compatibility with Ledger journals (Virtual posting costs), and is+     equivalent to 1 in hledger.++  5. Like 2, but as in 4 the '@@' is parenthesised, i.e.  '(@@)'; in+     hledger, this is equivalent to 2.++   Use the '-B/--cost' flag to convert amounts to their transaction+price's commodity, if any.  (mnemonic: "B" is from "cost Basis", as in+Ledger).  Eg here is how -B affects the balance report for the example+above:++$ hledger bal -N --flat+               $-135  assets:dollars+                €100  assets:euros+$ hledger bal -N --flat -B+               $-135  assets:dollars+                $135  assets:euros    # <- the euros' cost++   Note -B is sensitive to the order of postings when a transaction+price is inferred: the inferred price will be in the commodity of the+last amount.  So if example 3's postings are reversed, while the+transaction is equivalent, -B shows something different:++2009/1/1+  assets:dollars  $-135              ; 135 dollars sold+  assets:euros     €100              ; for 100 euros++$ hledger bal -N --flat -B+               €-100  assets:dollars  # <- the dollars' selling price+                €100  assets:euros+++File: hledger.info,  Node: Lot prices lot dates,  Next: Balance assertions,  Prev: Transaction prices,  Up: JOURNAL FORMAT++12.12 Lot prices, lot dates+===========================++Ledger allows another kind of price, lot price (four variants:+'{UNITPRICE}', '{{TOTALPRICE}}', '{=FIXEDUNITPRICE}',+'{{=FIXEDTOTALPRICE}}'), and/or a lot date ('[DATE]') to be specified.+These are normally used to select a lot when selling investments.+hledger will parse these, for compatibility with Ledger journals, but+currently ignores them.  A transaction price, lot price and/or lot date+may appear in any order, after the posting amount and before the balance+assertion if any.+++File: hledger.info,  Node: Balance assertions,  Next: Balance assignments,  Prev: Lot prices lot dates,  Up: JOURNAL FORMAT++12.13 Balance assertions+========================++hledger supports Ledger-style balance assertions in journal files.+These look like, for example, '= EXPECTEDBALANCE' following a posting's+amount.  Eg here we assert the expected dollar balance in accounts a and+b after each posting:++2013/1/1+  a   $1  =$1+  b       =$-1++2013/1/2+  a   $1  =$2+  b  $-1  =$-2++   After reading a journal file, hledger will check all balance+assertions and report an error if any of them fail.  Balance assertions+can protect you from, eg, inadvertently disrupting reconciled balances+while cleaning up old entries.  You can disable them temporarily with+the '-I/--ignore-assertions' flag, which can be useful for+troubleshooting or for reading Ledger files.  (Note: this flag currently+does not disable balance assignments, below).++* Menu:++* Assertions and ordering::+* Assertions and included files::+* Assertions and multiple -f options::+* Assertions and commodities::+* Assertions and prices::+* Assertions and subaccounts::+* Assertions and virtual postings::+* Assertions and precision::+++File: hledger.info,  Node: Assertions and ordering,  Next: Assertions and included files,  Up: Balance assertions++12.13.1 Assertions and ordering+-------------------------------++hledger sorts an account's postings and assertions first by date and+then (for postings on the same day) by parse order.  Note this is+different from Ledger, which sorts assertions only by parse order.+(Also, Ledger assertions do not see the accumulated effect of repeated+postings to the same account within a transaction.)++   So, hledger balance assertions keep working if you reorder+differently-dated transactions within the journal.  But if you reorder+same-dated transactions or postings, assertions might break and require+updating.  This order dependence does bring an advantage: precise+control over the order of postings and assertions within a day, so you+can assert intra-day balances.+++File: hledger.info,  Node: Assertions and included files,  Next: Assertions and multiple -f options,  Prev: Assertions and ordering,  Up: Balance assertions++12.13.2 Assertions and included files+-------------------------------------++With included files, things are a little more complicated.  Including+preserves the ordering of postings and assertions.  If you have multiple+postings to an account on the same day, split across different files,+and you also want to assert the account's balance on the same day,+you'll have to put the assertion in the right file.+++File: hledger.info,  Node: Assertions and multiple -f options,  Next: Assertions and commodities,  Prev: Assertions and included files,  Up: Balance assertions++12.13.3 Assertions and multiple -f options+------------------------------------------++Balance assertions don't work well across files specified with multiple+-f options.  Use include or concatenate the files instead.+++File: hledger.info,  Node: Assertions and commodities,  Next: Assertions and prices,  Prev: Assertions and multiple -f options,  Up: Balance assertions++12.13.4 Assertions and commodities+----------------------------------++The asserted balance must be a simple single-commodity amount, and in+fact the assertion checks only this commodity's balance within the+(possibly multi-commodity) account balance.  This is how assertions work+in Ledger also.  We could call this a "partial" balance assertion.++   To assert the balance of more than one commodity in an account, you+can write multiple postings, each asserting one commodity's balance.++   You can make a stronger "total" balance assertion by writing a double+equals sign ('== EXPECTEDBALANCE').  This asserts that there are no+other unasserted commodities in the account (or, that their balance is+0).++2013/1/1+  a   $1+  a    1€+  b  $-1+  c   -1€++2013/1/2  ; These assertions succeed+  a    0  =  $1+  a    0  =   1€+  b    0 == $-1+  c    0 ==  -1€++2013/1/3  ; This assertion fails as 'a' also contains 1€+  a    0 ==  $1++   It's not yet possible to make a complete assertion about a balance+that has multiple commodities.  One workaround is to isolate each+commodity into its own subaccount:++2013/1/1+  a:usd   $1+  a:euro   1€+  b++2013/1/2+  a        0 ==  0+  a:usd    0 == $1+  a:euro   0 ==  1€+++File: hledger.info,  Node: Assertions and prices,  Next: Assertions and subaccounts,  Prev: Assertions and commodities,  Up: Balance assertions++12.13.5 Assertions and prices+-----------------------------++Balance assertions ignore transaction prices, and should normally be+written without one:++2019/1/1+  (a)     $1 @ €1 = $1++   We do allow prices to be written there, however, and print shows+them, even though they don't affect whether the assertion passes or+fails.  This is for backward compatibility (hledger's close command used+to generate balance assertions with prices), and because balance+_assignments_ do use them (see below).+++File: hledger.info,  Node: Assertions and subaccounts,  Next: Assertions and virtual postings,  Prev: Assertions and prices,  Up: Balance assertions++12.13.6 Assertions and subaccounts+----------------------------------++The balance assertions above ('=' and '==') do not count the balance+from subaccounts; they check the account's exclusive balance only.  You+can assert the balance including subaccounts by writing '=*' or '==*',+eg:++2019/1/1+  equity:opening balances+  checking:a       5+  checking:b       5+  checking         1  ==* 11+++File: hledger.info,  Node: Assertions and virtual postings,  Next: Assertions and precision,  Prev: Assertions and subaccounts,  Up: Balance assertions++12.13.7 Assertions and virtual postings+---------------------------------------++Balance assertions are checked against all postings, both real and+virtual.  They are not affected by the '--real/-R' flag or 'real:'+query.+++File: hledger.info,  Node: Assertions and precision,  Prev: Assertions and virtual postings,  Up: Balance assertions++12.13.8 Assertions and precision+--------------------------------++Balance assertions compare the exactly calculated amounts, which are not+always what is shown by reports.  Eg a commodity directive may limit the+display precision, but this will not affect balance assertions.  Balance+assertion failure messages show exact amounts.+++File: hledger.info,  Node: Balance assignments,  Next: Directives,  Prev: Balance assertions,  Up: JOURNAL FORMAT++12.14 Balance assignments+=========================++Ledger-style balance assignments are also supported.  These are like+balance assertions, but with no posting amount on the left side of the+equals sign; instead it is calculated automatically so as to satisfy the+assertion.  This can be a convenience during data entry, eg when setting+opening balances:++; starting a new journal, set asset account balances+2016/1/1 opening balances+  assets:checking            = $409.32+  assets:savings             = $735.24+  assets:cash                 = $42+  equity:opening balances++   or when adjusting a balance to reality:++; no cash left; update balance, record any untracked spending as a generic expense+2016/1/15+  assets:cash    = $0+  expenses:misc++   The calculated amount depends on the account's balance in the+commodity at that point (which depends on the previously-dated postings+of the commodity to that account since the last balance assertion or+assignment).  Note that using balance assignments makes your journal a+little less explicit; to know the exact amount posted, you have to run+hledger or do the calculations yourself, instead of just reading it.++* Menu:++* Balance assignments and prices::+++File: hledger.info,  Node: Balance assignments and prices,  Up: Balance assignments++12.14.1 Balance assignments and prices+--------------------------------------++A transaction price in a balance assignment will cause the calculated+amount to have that price attached:++2019/1/1+  (a)             = $1 @ €2++$ hledger print --explicit+2019-01-01+    (a)         $1 @ €2 = $1 @ €2+++File: hledger.info,  Node: Directives,  Next: Directives and multiple files,  Prev: Balance assignments,  Up: JOURNAL FORMAT++12.15 Directives+================++A directive is a line in the journal beginning with a special keyword,+that influences how the journal is processed, how things are displayed,+and so on.  hledger's directives are based on (a subset of) Ledger's,+but there are many differences, and also some differences between+hledger versions.  Here are some more definitions:++   * _subdirective_ - Some directives support subdirectives, written+     indented below the parent directive.++   * _decimal mark_ - The character to interpret as a decimal mark+     (period or comma) when parsing amounts of a commodity.++   * _display style_ - How to display amounts of a commodity in output:+     symbol side and spacing, digit groups, decimal mark, and number of+     decimal places.++   Directives are not required when starting out with hledger, but you+will probably add some as your needs grow.  Here is an overview of+directives by purpose:++purpose                          directives             command line+                                                        options with+                                                        similar effect+---------------------------------------------------------------------------+*READING/GENERATING DATA:*+Declare a commodity's or         'commodity', 'D',+file's decimal mark to help      'decimal-mark'+parse amounts accurately+Apply changes to the data        'alias', 'apply        '--alias'+while parsing                    account', 'comment',+                                 'D', 'Y'+Inline extra data files          'include'              multiple+                                                        '-f/--file''s+Generate extra transactions or   '~'+budget goals+Generate extra postings          '='+*CHECKING FOR ERRORS:*+Define valid entities to allow   'account',+stricter error checking          'commodity', 'payee'+*DISPLAYING REPORTS:*+Declare accounts' display        'account'+order and accounting type+Declare commodity display        'commodity', 'D'       '-c/--commodity-style'+styles++   And here are all the directives and their precise effects:++directiveeffects                                                      ends+                                                                      at+                                                                      file+                                                                      end?+---------------------------------------------------------------------------+*'account'*Declares an account, for checking all entries in all files;+      and its display order and type, for reports.  Subdirectives:+      any text, ignored.+*'alias'*Rewrites account names, in following entries until end of    Y+      current file or 'end aliases'.+*'applyPrepends a common parent account to all account names, in      Y+account'*following entries until end of current file or 'end apply+      account'.+*'comment'*Ignores part of the journal file, until end of current fileY+      or 'end comment'.+*'commodity'*Declares a commodity, for checking all entries in all files;N,+      the decimal mark for parsing amounts of this commodity, for     Y+      following entries until end of current file; and its display+      style, for reports.  Takes precedence over 'D'.+      Subdirectives: 'format' (alternate syntax).+*'D'* Sets a default commodity to use for no-symbol amounts, and      Y+      its decimal mark for parsing amounts of this commodity in+      following entries until end of current file; and its display+      style, for reports.+*'decimal-mark'*Declares the decimal mark, for parsing amounts of all Y+      commodities in following entries until next 'decimal-mark' or+      end of current file.  Included files can override.  Takes+      precedence over 'commodity' and 'D'.+*'include'*Includes entries and directives from another file, as if they+      were written inline.+*'payee'*Declares a payee name, for checking all entries in all files.+*'P'* Declares a market price for a commodity on some date, for+      valuation reports.+*'Y'* Declares a year for yearless dates, for following entries       Y+      until end of current file.+*'~'* Declares a periodic transaction rule that generates future+(tilde)transactions with '--forecast' and budget goals with 'balance+      --budget'.+*'='* Declares an auto posting rule that generates extra postings     partly+(equals)on matched transactions with '--auto', in current, parent,+      and child files (but not sibling files, see #1212).+++File: hledger.info,  Node: Directives and multiple files,  Next: Comment blocks,  Prev: Directives,  Up: JOURNAL FORMAT++12.16 Directives and multiple files+===================================++If you use multiple '-f'/'--file' options, or the 'include' directive,+hledger will process multiple input files.  But directives which affect+input typically have effect only until the end of the file in which they+occur (and on any included files in that region).++   This may seem inconvenient, but it's intentional; it makes reports+stable and deterministic, independent of the order of input.  Otherwise+you could see different numbers if you happened to write -f options in a+different order, or if you moved includes around while cleaning up your+files.++   It can be surprising though; for example, it means that 'alias'+directives do not affect parent or sibling files (see below).+++File: hledger.info,  Node: Comment blocks,  Next: Including other files,  Prev: Directives and multiple files,  Up: JOURNAL FORMAT++12.17 Comment blocks+====================++A line containing just 'comment' starts a commented region of the file,+and a line containing just 'end comment' (or the end of the current+file) ends it.  See also comments.+++File: hledger.info,  Node: Including other files,  Next: Default year,  Prev: Comment blocks,  Up: JOURNAL FORMAT++12.18 Including other files+===========================++You can pull in the content of additional files by writing an include+directive, like this:++include FILEPATH++   Only journal files can include, and only journal, timeclock or+timedot files can be included (not CSV files, currently).++   If the file path does not begin with a slash, it is relative to the+current file's folder.++   A tilde means home directory, eg: 'include ~/main.journal'.++   The path may contain glob patterns to match multiple files, eg:+'include *.journal'.++   There is limited support for recursive wildcards: '**/' (the slash is+required) matches 0 or more subdirectories.  It's not super convenient+since you have to avoid include cycles and including directories, but+this can be done, eg: 'include */**/*.journal'.++   The path may also be prefixed to force a specific file format,+overriding the file extension (as described in hledger.1 -> Input+files): 'include timedot:~/notes/2020*.md'.+++File: hledger.info,  Node: Default year,  Next: Declaring payees,  Prev: Including other files,  Up: JOURNAL FORMAT++12.19 Default year+==================++You can set a default year to be used for subsequent dates which don't+specify a year.  This is a line beginning with 'Y' followed by the year.+Eg:++Y2009  ; set default year to 2009++12/15  ; equivalent to 2009/12/15+  expenses  1+  assets++Y2010  ; change default year to 2010++2009/1/30  ; specifies the year, not affected+  expenses  1+  assets++1/31   ; equivalent to 2010/1/31+  expenses  1+  assets+++File: hledger.info,  Node: Declaring payees,  Next: Declaring the decimal mark,  Prev: Default year,  Up: JOURNAL FORMAT++12.20 Declaring payees+======================++The 'payee' directive can be used to declare a limited set of payees+which may appear in transaction descriptions.  The "payees" check will+report an error if any transaction refers to a payee that has not been+declared.  Eg:++payee Whole Foods+++File: hledger.info,  Node: Declaring the decimal mark,  Next: Declaring commodities,  Prev: Declaring payees,  Up: JOURNAL FORMAT++12.21 Declaring the decimal mark+================================++You can use a 'decimal-mark' directive - usually one per file, at the+top of the file - to declare which character represents a decimal mark+when parsing amounts in this file.  It can look like++decimal-mark .++   or++decimal-mark ,++   This prevents any ambiguity when parsing numbers in the file, so we+recommend it, especially if the file contains digit group marks (eg+thousands separators).+++File: hledger.info,  Node: Declaring commodities,  Next: Default commodity,  Prev: Declaring the decimal mark,  Up: JOURNAL FORMAT++12.22 Declaring commodities+===========================++You can use 'commodity' directives to declare your commodities.  In fact+the 'commodity' directive performs several functions at once:++  1. It declares commodities which may be used in the journal.  This can+     optionally be enforced, providing useful error checking.  (Cf+     Commodity error checking)++  2. It declares which decimal mark character (period or comma), to+     expect when parsing input - useful to disambiguate international+     number formats in your data.  Without this, hledger will parse both+     '1,000' and '1.000' as 1.  (Cf Amounts)++  3. It declares how to render the commodity's amounts when displaying+     output - the decimal mark, any digit group marks, the number of+     decimal places, symbol placement and so on.  (Cf Commodity display+     style)++   You will run into one of the problems solved by commodity directives+sooner or later, so we recommend using them, for robust and predictable+parsing and display.++   Generally you should put them at the top of your journal file (since+for function 2, they affect only following amounts, cf #793).++   A commodity directive is just the word 'commodity' followed by a+sample amount, like this:++;commodity SAMPLEAMOUNT++commodity $1000.00+commodity 1,000.0000 AAAA  ; optional same-line comment++   It may also be written on multiple lines, and use the 'format'+subdirective, as in Ledger.  Note in this case the commodity symbol+appears twice; it must be the same in both places:++;commodity SYMBOL+;  format SAMPLEAMOUNT++; display indian rupees with currency name on the left,+; thousands, lakhs and crores comma-separated,+; period as decimal point, and two decimal places.+commodity INR+  format INR 1,00,00,000.00++   Remember that if the commodity symbol contains spaces, numbers, or+punctuation, it must be enclosed in double quotes (cf Commodity).++   The amount's quantity does not matter; only the format is+significant.  It must include a decimal mark - either a period or a+comma - followed by 0 or more decimal digits.++   A few more examples:++# number formats for $, EUR, INR and the no-symbol commodity:+commodity $1,000.00+commodity EUR 1.000,00+commodity INR 9,99,99,999.0+commodity 1 000 000.++   Note hledger normally uses banker's rounding, so 0.5 displayed with+zero decimal digits is "0".  (More at Commodity display style.)++   Even in the presence of commodity directives, the commodity display+style can still be overridden by supplying a command line option.++* Menu:++* Commodity error checking::+++File: hledger.info,  Node: Commodity error checking,  Up: Declaring commodities++12.22.1 Commodity error checking+--------------------------------++In strict mode, enabled with the '-s'/'--strict' flag, hledger will+report an error if a commodity symbol is used that has not been declared+by a 'commodity' directive.  This works similarly to account error+checking, see the notes there for more details.++   Note, this disallows amounts without a commodity symbol, because+currently it's not possible (?)  to declare the "no-symbol" commodity+with a directive.  This is one exception for convenience: zero amounts+are always allowed to have no commodity symbol.+++File: hledger.info,  Node: Default commodity,  Next: Declaring market prices,  Prev: Declaring commodities,  Up: JOURNAL FORMAT++12.23 Default commodity+=======================++The 'D' directive sets a default commodity, to be used for any+subsequent commodityless amounts (ie, plain numbers) seen while parsing+the journal.  This effect lasts until the next 'D' directive, or the end+of the journal.++   For compatibility/historical reasons, 'D' also acts like a+'commodity' directive (setting the commodity's decimal mark for parsing+and display style for output).++   The syntax is 'D AMOUNT'.  As with 'commodity', the amount must+include a decimal mark (either period or comma).  Eg:++; commodity-less amounts should be treated as dollars+; (and displayed with the dollar sign on the left, thousands separators and two decimal places)+D $1,000.00++1/1+  a     5  ; <- commodity-less amount, parsed as $5 and displayed as $5.00+  b++   If both 'commodity' and 'D' directives are found for a commodity,+'commodity' takes precedence for setting decimal mark and display style.++   If you are using 'D' and also checking commodities, you will need to+add a 'commodity' directive similar to the 'D'.  (The 'hledger check+commodities' command expects 'commodity' directives, and ignores 'D').+++File: hledger.info,  Node: Declaring market prices,  Next: Declaring accounts,  Prev: Default commodity,  Up: JOURNAL FORMAT++12.24 Declaring market prices+=============================++The 'P' directive declares a market price, which is an exchange rate+between two commodities on a certain date.  (In Ledger, they are called+"historical prices".)  These are often obtained from a stock exchange,+cryptocurrency exchange, or the foreign exchange market.++   The format is:++P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT++   DATE is a simple date, COMMODITY1SYMBOL is the symbol of the+commodity being priced, and COMMODITY2AMOUNT is the amount (symbol and+quantity) of commodity 2 that one unit of commodity 1 is worth on this+date.  Examples:++# one euro was worth $1.35 from 2009-01-01 onward:+P 2009-01-01 € $1.35++# and $1.40 from 2010-01-01 onward:+P 2010-01-01 € $1.40++   The '-V', '-X' and '--value' flags use these market prices to show+amount values in another commodity.  See Valuation.+++File: hledger.info,  Node: Declaring accounts,  Next: Rewriting accounts,  Prev: Declaring market prices,  Up: JOURNAL FORMAT++12.25 Declaring accounts+========================++'account' directives can be used to declare accounts (ie, the places+that amounts are transferred from and to).  Though not required, these+declarations can provide several benefits:++   * They can document your intended chart of accounts, providing a+     reference.+   * They control account display order in reports, allowing+     non-alphabetic sorting (eg Revenues to appear above Expenses).+   * They can help hledger know your accounts' types (asset, liability,+     equity, revenue, expense), useful for reports like balancesheet and+     incomestatement.+   * They can store other account information, as comments or as tags+     which can be used to filter reports.+   * They help with account name completion (in hledger add,+     hledger-web, hledger-iadd, ledger-mode, etc.)+   * In strict mode, they restrict which accounts may be posted to by+     transactions, which helps detect typos.++   The simplest form is just the word 'account' followed by a+hledger-style account name, eg this account directive declares the+'assets:bank:checking' account:++account assets:bank:checking++* Menu:++* Account error checking::+* Account comments::+* Account subdirectives::+* Account types::+* Account display order::+++File: hledger.info,  Node: Account error checking,  Next: Account comments,  Up: Declaring accounts++12.25.1 Account error checking+------------------------------++By default, accounts come into existence when a transaction references+them by name.  This is convenient, but it means hledger can't warn you+when you mis-spell an account name in the journal.  Usually you'll find+the error later, as an extra account in balance reports, or an incorrect+balance when reconciling.++   In strict mode, enabled with the '-s'/'--strict' flag, hledger will+report an error if any transaction uses an account name that has not+been declared by an account directive.  Some notes:++   * The declaration is case-sensitive; transactions must use the+     correct account name capitalisation.+   * The account directive's scope is "whole file and below" (see+     directives).  This means it affects all of the current file, and+     any files it includes, but not parent or sibling files.  The+     position of account directives within the file does not matter,+     though it's usual to put them at the top.+   * Accounts can only be declared in 'journal' files (but will affect+     included files in other formats).+   * It's currently not possible to declare "all possible subaccounts"+     with a wildcard; every account posted to must be declared.+++File: hledger.info,  Node: Account comments,  Next: Account subdirectives,  Prev: Account error checking,  Up: Declaring accounts++12.25.2 Account comments+------------------------++Comments, beginning with a semicolon, can be added:++   * on the same line, *after two or more spaces* (because ; is allowed+     in account names)+   * on the next lines, indented++   An example of both:++account assets:bank:checking    ; same-line comment, note 2+ spaces required before ;+  ; next-line comment+  ; some tags, type:A, acctnum:12345++   Compatibility note: same-line comments are not supported by Ledger or+hledger <1.13.+++File: hledger.info,  Node: Account subdirectives,  Next: Account types,  Prev: Account comments,  Up: Declaring accounts++12.25.3 Account subdirectives+-----------------------------++We also allow (and ignore) Ledger-style indented subdirectives, just for+compatibility.:++account assets:bank:checking+  format blah blah  ; <- subdirective, ignored++   Here is the full syntax of account directives:++account ACCTNAME  [;type:ACCTTYPE] [COMMENT]+  [;COMMENTS]+  [LEDGER-STYLE SUBDIRECTIVES, IGNORED]+++File: hledger.info,  Node: Account types,  Next: Account display order,  Prev: Account subdirectives,  Up: Declaring accounts++12.25.4 Account types+---------------------++hledger knows that accounts come in several types: assets, liabilities,+expenses and so on.  This enables easy reports like balancesheet and+incomestatement, and filtering by account type with the 'type:' query.++   As a convenience, hledger will detect these account types+automatically if you are using common english-language top-level account+names (described below).  But generally we recommend you declare types+explicitly, by adding a 'type:' tag to your top-level account+directives.  Subaccounts will inherit the type of their parent.  The+tag's value should be one of the five main account types:++   * 'A' or 'Asset' (things you own)+   * 'L' or 'Liability' (things you owe)+   * 'E' or 'Equity' (investment/ownership; balanced counterpart of+     assets & liabilities)+   * 'R' or 'Revenue' (what you received money from, AKA income;+     technically part of Equity)+   * 'X' or 'Expense' (what you spend money on; technically part of+     Equity)++   or, it can be (these are used less often):++   * 'C' or 'Cash' (a subtype of Asset, indicating liquid assets for the+     cashflow report)+   * 'V' or 'Conversion' (a subtype of Equity, for conversions (see+     CONVERSION & COST).)++   Here is a typical set of account type declarations:++account assets             ; type: A+account liabilities        ; type: L+account equity             ; type: E+account revenues           ; type: R+account expenses           ; type: X++account assets:bank        ; type: C+account assets:cash        ; type: C++account equity:conversion  ; type: V++   Here are some tips for working with account types.++   * The rules for inferring types from account names are as follows.+     These are just a convenience that sometimes help new users get+     going; if they don't work for you, just ignore them and declare+     your account types.  See also Regular expressions.  Note the Cash+     regexp changed in hledger 1.24.99.2.++     If account's name contains this (CI) regular expression:            | its type is:+     --------------------------------------------------------------------|-------------+     ^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|current)(:|$) | Cash+     ^assets?(:|$)                                                       | Asset+     ^(debts?|liabilit(y|ies))(:|$)                                      | Liability+     ^equity:(trad(e|ing)|conversion)s?(:|$)                             | Conversion+     ^equity(:|$)                                                        | Equity+     ^(income|revenue)s?(:|$)                                            | Revenue+     ^expenses?(:|$)                                                     | Expense++   * If you declare any account types, it's a good idea to declare an+     account for each of them, because a mixture of declared and+     name-inferred types can disrupt certain reports.++   * Certain uses of account aliases can disrupt account types.  See+     Rewriting accounts > Aliases and account types.++   * As mentioned above, subaccounts will inherit a type from their+     parent account.  To be precise, an account's type is decided by the+     first of these that exists:++       1. A 'type:' declaration for this account.+       2. A 'type:' declaration in the parent accounts above it,+          preferring the nearest.+       3. An account type inferred from this account's name.+       4. An account type inferred from a parent account's name,+          preferring the nearest parent.+       5. Otherwise, it will have no type.++   * For troubleshooting, you can list accounts and their types with:++     $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES]+++File: hledger.info,  Node: Account display order,  Prev: Account types,  Up: Declaring accounts++12.25.5 Account display order+-----------------------------++Account directives also set the order in which accounts are displayed,+eg in reports, the hledger-ui accounts screen, and the hledger-web+sidebar.  By default accounts are listed in alphabetical order.  But if+you have these account directives in the journal:++account assets+account liabilities+account equity+account revenues+account expenses++   you'll see those accounts displayed in declaration order, not+alphabetically:++$ hledger accounts -1+assets+liabilities+equity+revenues+expenses++   Undeclared accounts, if any, are displayed last, in alphabetical+order.++   Note that sorting is done at each level of the account tree (within+each group of sibling accounts under the same parent).  And currently,+this directive:++account other:zoo++   would influence the position of 'zoo' among 'other''s subaccounts,+but not the position of 'other' among the top-level accounts.  This+means:++   * you will sometimes declare parent accounts (eg 'account other'+     above) that you don't intend to post to, just to customize their+     display order+   * sibling accounts stay together (you couldn't display 'x:y' in+     between 'a:b' and 'a:c').+++File: hledger.info,  Node: Rewriting accounts,  Next: Default parent account,  Prev: Declaring accounts,  Up: JOURNAL FORMAT++12.26 Rewriting accounts+========================++You can define account alias rules which rewrite your account names, or+parts of them, before generating reports.  This can be useful for:++   * expanding shorthand account names to their full form, allowing+     easier data entry and a less verbose journal+   * adapting old journals to your current chart of accounts+   * experimenting with new account organisations, like a new hierarchy+   * combining two accounts into one, eg to see their sum or difference+     on one line+   * customising reports++   Account aliases also rewrite account names in account directives.+They do not affect account names being entered via hledger add or+hledger-web.++   Account aliases are very powerful.  They are generally easy to use+correctly, but you can also generate invalid account names with them;+more on this below.++   See also Rewrite account names.++* Menu:++* Basic aliases::+* Regex aliases::+* Combining aliases::+* Aliases and multiple files::+* end aliases::+* Aliases can generate bad account names::+* Aliases and account types::+++File: hledger.info,  Node: Basic aliases,  Next: Regex aliases,  Up: Rewriting accounts++12.26.1 Basic aliases+---------------------++To set an account alias, use the 'alias' directive in your journal file.+This affects all subsequent journal entries in the current file or its+included files (but note: not sibling or parent files).  The spaces+around the = are optional:++alias OLD = NEW++   Or, you can use the '--alias 'OLD=NEW'' option on the command line.+This affects all entries.  It's useful for trying out aliases+interactively.++   OLD and NEW are case sensitive full account names.  hledger will+replace any occurrence of the old account name with the new one.+Subaccounts are also affected.  Eg:++alias checking = assets:bank:wells fargo:checking+; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"+++File: hledger.info,  Node: Regex aliases,  Next: Combining aliases,  Prev: Basic aliases,  Up: Rewriting accounts++12.26.2 Regex aliases+---------------------++There is also a more powerful variant that uses a regular expression,+indicated by the forward slashes:++alias /REGEX/ = REPLACEMENT++   or '--alias '/REGEX/=REPLACEMENT''.++   REGEX is a case-insensitive regular expression.  Anywhere it matches+inside an account name, the matched part will be replaced by+REPLACEMENT. If REGEX contains parenthesised match groups, these can be+referenced by the usual numeric backreferences in REPLACEMENT. Eg:++alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3+; rewrites "assets:bank:wells fargo:checking" to  "assets:wells fargo checking"++   Also note that REPLACEMENT continues to the end of line (or on+command line, to end of option argument), so it can contain trailing+whitespace.+++File: hledger.info,  Node: Combining aliases,  Next: Aliases and multiple files,  Prev: Regex aliases,  Up: Rewriting accounts++12.26.3 Combining aliases+-------------------------++You can define as many aliases as you like, using journal directives+and/or command line options.++   Recursive aliases - where an account name is rewritten by one alias,+then by another alias, and so on - are allowed.  Each alias sees the+effect of previously applied aliases.++   In such cases it can be important to understand which aliases will be+applied and in which order.  For (each account name in) each journal+entry, we apply:++  1. 'alias' directives preceding the journal entry, most recently+     parsed first (ie, reading upward from the journal entry, bottom to+     top)+  2. '--alias' options, in the order they appeared on the command line+     (left to right).++   In other words, for (an account name in) a given journal entry:++   * the nearest alias declaration before/above the entry is applied+     first+   * the next alias before/above that will be be applied next, and so on+   * aliases defined after/below the entry do not affect it.++   This gives nearby aliases precedence over distant ones, and helps+provide semantic stability - aliases will keep working the same way+independent of which files are being read and in which order.++   In case of trouble, adding '--debug=6' to the command line will show+which aliases are being applied when.+++File: hledger.info,  Node: Aliases and multiple files,  Next: end aliases,  Prev: Combining aliases,  Up: Rewriting accounts++12.26.4 Aliases and multiple files+----------------------------------++As explained at Directives and multiple files, 'alias' directives do not+affect parent or sibling files.  Eg in this command,++hledger -f a.aliases -f b.journal++   account aliases defined in a.aliases will not affect b.journal.+Including the aliases doesn't work either:++include a.aliases++2020-01-01  ; not affected by a.aliases+  foo  1+  bar++   This means that account aliases should usually be declared at the+start of your top-most file, like this:++alias foo=Foo+alias bar=Bar++2020-01-01  ; affected by aliases above+  foo  1+  bar++include c.journal  ; also affected+++File: hledger.info,  Node: end aliases,  Next: Aliases can generate bad account names,  Prev: Aliases and multiple files,  Up: Rewriting accounts++12.26.5 'end aliases'+---------------------++You can clear (forget) all currently defined aliases (seen in the+journal so far, or defined on the command line) with this directive:++end aliases+++File: hledger.info,  Node: Aliases can generate bad account names,  Next: Aliases and account types,  Prev: end aliases,  Up: Rewriting accounts++12.26.6 Aliases can generate bad account names+----------------------------------------------++Be aware that account aliases can produce malformed account names, which+could cause confusing reports or invalid 'print' output.  For example,+you could erase all account names:++2021-01-01+  a:aa     1+  b++$ hledger print --alias '/.*/='+2021-01-01+                   1++   The above 'print' output is not a valid journal.  Or you could insert+an illegal double space, causing 'print' output that would give a+different journal when reparsed:++2021-01-01+  old    1+  other++$ hledger print --alias old="new  USD" | hledger -f- print+2021-01-01+    new             USD 1+    other+++File: hledger.info,  Node: Aliases and account types,  Prev: Aliases can generate bad account names,  Up: Rewriting accounts++12.26.7 Aliases and account types+---------------------------------++If an account with a type declaration (see Declaring accounts > Account+types) is renamed by an alias, normally the account type remains in+effect.++   However, renaming in a way that reshapes the account tree (eg+renaming parent accounts but not their children, or vice versa) could+prevent child accounts from inheriting the account type of their+parents.++   Secondly, if an account's type is being inferred from its name,+renaming it by an alias could prevent or alter that.++   If you are using account aliases and the 'type:' query is not+matching accounts as you expect, try troubleshooting with the accounts+command, eg something like:++$ hledger accounts --alias assets=bassetts type:a+++File: hledger.info,  Node: Default parent account,  Next: Periodic transactions,  Prev: Rewriting accounts,  Up: JOURNAL FORMAT++12.27 Default parent account+============================++You can specify a parent account which will be prepended to all accounts+within a section of the journal.  Use the 'apply account' and 'end apply+account' directives like so:++apply account home++2010/1/1+    food    $10+    cash++end apply account++   which is equivalent to:++2010/01/01+    home:food           $10+    home:cash          $-10++   If 'end apply account' is omitted, the effect lasts to the end of the+file.  Included files are also affected, eg:++apply account business+include biz.journal+end apply account+apply account personal+include personal.journal++   Prior to hledger 1.0, legacy 'account' and 'end' spellings were also+supported.++   A default parent account also affects account directives.  It does+not affect account names being entered via hledger add or hledger-web.+If account aliases are present, they are applied after the default+parent account.+++File: hledger.info,  Node: Periodic transactions,  Next: Auto postings,  Prev: Default parent account,  Up: JOURNAL FORMAT++12.28 Periodic transactions+===========================++Periodic transaction rules describe transactions that recur.  They allow+hledger to generate temporary future transactions to help with+forecasting, so you don't have to write out each one in the journal, and+it's easy to try out different forecasts.++   Periodic transactions can be a little tricky, so before you use them,+read this whole section - or at least these tips:++  1. Two spaces accidentally added or omitted will cause you trouble -+     read about this below.+  2. For troubleshooting, show the generated transactions with 'hledger+     print --forecast tag:generated' or 'hledger register --forecast+     tag:generated'.+  3. Forecasted transactions will begin only after the last+     non-forecasted transaction's date.+  4. Forecasted transactions will end 6 months from today, by default.+     See below for the exact start/end rules.+  5. period expressions can be tricky.  Their documentation needs+     improvement, but is worth studying.+  6. Some period expressions with a repeating interval must begin on a+     natural boundary of that interval.  Eg in 'weekly from DATE', DATE+     must be a monday.  '~ weekly from 2019/10/1' (a tuesday) will give+     an error.+  7. Other period expressions with an interval are automatically+     expanded to cover a whole number of that interval.  (This is done+     to improve reports, but it also affects periodic transactions.+     Yes, it's a bit inconsistent with the above.)  Eg: '~ every 10th+     day of month from 2020/01', which is equivalent to '~ every 10th+     day of month from 2020/01/01', will be adjusted to start on+     2019/12/10.++   Periodic transaction rules also have a second meaning: they are used+to define budget goals, shown in budget reports.++* Menu:++* Periodic rule syntax::+* Two spaces between period expression and description!::+* Forecasting with periodic transactions::+* Budgeting with periodic transactions::+++File: hledger.info,  Node: Periodic rule syntax,  Next: Two spaces between period expression and description!,  Up: Periodic transactions++12.28.1 Periodic rule syntax+----------------------------++A periodic transaction rule looks like a normal journal entry, with the+date replaced by a tilde ('~') followed by a period expression+(mnemonic: '~' looks like a recurring sine wave.):++~ monthly+    expenses:rent          $2000+    assets:bank:checking++   There is an additional constraint on the period expression: the start+date must fall on a natural boundary of the interval.  Eg 'monthly from+2018/1/1' is valid, but 'monthly from 2018/1/15' is not.++   Partial or relative dates (M/D, D, tomorrow, last week) in the period+expression can work (useful or not).  They will be relative to today's+date, unless a Y default year directive is in effect, in which case they+will be relative to Y/1/1.+++File: hledger.info,  Node: Two spaces between period expression and description!,  Next: Forecasting with periodic transactions,  Prev: Periodic rule syntax,  Up: Periodic transactions++12.28.2 Two spaces between period expression and description!+-------------------------------------------------------------++If the period expression is followed by a transaction description, these+must be separated by *two or more spaces*.  This helps hledger know+where the period expression ends, so that descriptions can not+accidentally alter their meaning, as in this example:++; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2020"+;               ||+;               vv+~ every 2 months  in 2020, we will review+    assets:bank:checking   $1500+    income:acme inc++   So,++   * Do write two spaces between your period expression and your+     transaction description, if any.+   * Don't accidentally write two spaces in the middle of your period+     expression.+++File: hledger.info,  Node: Forecasting with periodic transactions,  Next: Budgeting with periodic transactions,  Prev: Two spaces between period expression and description!,  Up: Periodic transactions++12.28.3 Forecasting with periodic transactions+----------------------------------------------++The '--forecast' flag activates any periodic transaction rules in the+journal.  These will generate temporary additional transactions, usually+recurring and in the future, which will appear in all reports.  'hledger+print --forecast' is a good way to see them.++   This can be useful for estimating balances into the future, perhaps+experimenting with different scenarios.++   It could also be useful for scripted data entry: you could describe+recurring transactions, and every so often copy the output of 'print+--forecast' into the journal.++   The generated transactions will have an extra tag, like+'generated-transaction:~ PERIODICEXPR', indicating which periodic rule+generated them.  There is also a similar, hidden tag, named+'_generated-transaction:', which you can use to reliably match+transactions generated "just now" (rather than 'print'ed in the past).++   The forecast transactions are generated within a _forecast period_,+which is independent of the report period.  (Forecast period sets the+bounds for generated transactions, report period controls which+transactions are reported.)  The forecast period begins on:++   * the start date provided within '--forecast''s argument, if any+   * otherwise, the later of+        * the report start date, if specified (with '-b'/'-p'/'date:')+        * the day after the latest ordinary transaction in the journal,+          if any++   * otherwise today.++   It ends on:++   * the end date provided within '--forecast''s argument, if any+   * otherwise, the report end date, if specified (with+     '-e'/'-p'/'date:')+   * otherwise 180 days (6 months) from today.++   Note, this means that ordinary transactions will suppress periodic+transactions, by default; the periodic transactions will not start until+after the last ordinary transaction.  This is usually convenient, but+you can get around it in two ways:++   * If you need to record some transactions in the future, make them+     periodic transactions (with a single occurrence, eg: '~+     YYYY-MM-DD') rather than ordinary transactions.  That way they+     won't suppress other periodic transactions.++   * Or give '--forecast' a period expression argument.  A forecast+     period specified this way can overlap ordinary transactions, and+     need not be in the future.  Some things to note:++        * You must use '=' between flag and argument; a space won't+          work.+        * The period expression can specify the forecast period's start+          date, end date, or both.  See also Report start & end date.+        * The period expression should not specify a report interval.+          (Each periodic transaction rule specifies its own interval.)++   Some examples: '--forecast=202001-202004', '--forecast=jan-',+'--forecast=2021'.+++File: hledger.info,  Node: Budgeting with periodic transactions,  Prev: Forecasting with periodic transactions,  Up: Periodic transactions++12.28.4 Budgeting with periodic transactions+--------------------------------------------++With the '--budget' flag, currently supported by the balance command,+each periodic transaction rule declares recurring budget goals for the+specified accounts.  Eg the first example above declares a goal of+spending $2000 on rent (and also, a goal of depositing $2000 into+checking) every month.  Goals and actual performance can then be+compared in budget reports.++   See also: Budgeting and Forecasting.+++File: hledger.info,  Node: Auto postings,  Prev: Periodic transactions,  Up: JOURNAL FORMAT++12.29 Auto postings+===================++"Automated postings" or "auto postings" are extra postings which get+added automatically to transactions which match certain queries, defined+by "auto posting rules", when you use the '--auto' flag.++   An auto posting rule looks a bit like a transaction:++= QUERY+    ACCOUNT  AMOUNT+    ...+    ACCOUNT  [AMOUNT]++   except the first line is an equals sign (mnemonic: '=' suggests+matching), followed by a query (which matches existing postings), and+each "posting" line describes a posting to be generated, and the posting+amounts can be:++   * a normal amount with a commodity symbol, eg '$2'.  This will be+     used as-is.+   * a number, eg '2'.  The commodity symbol (if any) from the matched+     posting will be added to this.+   * a numeric multiplier, eg '*2' (a star followed by a number N). The+     matched posting's amount (and total price, if any) will be+     multiplied by N.+   * a multiplier with a commodity symbol, eg '*$2' (a star, number N,+     and symbol S). The matched posting's amount will be multiplied by+     N, and its commodity symbol will be replaced with S.++   Any query term containing spaces must be enclosed in single or double+quotes, as on the command line.  Eg, note the quotes around the second+query term below:++= expenses:groceries 'expenses:dining out'+    (budget:funds:dining out)                 *-1++   Some examples:++; every time I buy food, schedule a dollar donation+= expenses:food+    (liabilities:charity)   $-1++; when I buy a gift, also deduct that amount from a budget envelope subaccount+= expenses:gifts+    assets:checking:gifts  *-1+    assets:checking         *1++2017/12/1+  expenses:food    $10+  assets:checking++2017/12/14+  expenses:gifts   $20+  assets:checking++$ hledger print --auto+2017-12-01+    expenses:food              $10+    assets:checking+    (liabilities:charity)      $-1++2017-12-14+    expenses:gifts             $20+    assets:checking+    assets:checking:gifts     -$20+    assets:checking            $20++* Menu:++* Auto postings and multiple files::+* Auto postings and dates::+* Auto postings and transaction balancing / inferred amounts / balance assertions::+* Auto posting tags::+++File: hledger.info,  Node: Auto postings and multiple files,  Next: Auto postings and dates,  Up: Auto postings++12.29.1 Auto postings and multiple files+----------------------------------------++An auto posting rule can affect any transaction in the current file, or+in any parent file or child file.  Note, currently it will not affect+sibling files (when multiple '-f'/'--file' are used - see #1212).+++File: hledger.info,  Node: Auto postings and dates,  Next: Auto postings and transaction balancing / inferred amounts / balance assertions,  Prev: Auto postings and multiple files,  Up: Auto postings++12.29.2 Auto postings and dates+-------------------------------++A posting date (or secondary date) in the matched posting, or (taking+precedence) a posting date in the auto posting rule itself, will also be+used in the generated posting.+++File: hledger.info,  Node: Auto postings and transaction balancing / inferred amounts / balance assertions,  Next: Auto posting tags,  Prev: Auto postings and dates,  Up: Auto postings++12.29.3 Auto postings and transaction balancing / inferred amounts /+--------------------------------------------------------------------++balance assertions Currently, auto postings are added:++   * after missing amounts are inferred, and transactions are checked+     for balancedness,+   * but before balance assertions are checked.++   Note this means that journal entries must be balanced both before and+after auto postings are added.  This changed in hledger 1.12+; see #893+for background.++   This also means that you cannot have more than one auto-posting with+a missing amount applied to a given transaction, as it will be unable to+infer amounts.+++File: hledger.info,  Node: Auto posting tags,  Prev: Auto postings and transaction balancing / inferred amounts / balance assertions,  Up: Auto postings++12.29.4 Auto posting tags+-------------------------++Automated postings will have some extra tags:++   * 'generated-posting:= QUERY' - shows this was generated by an auto+     posting rule, and the query+   * '_generated-posting:= QUERY' - a hidden tag, which does not appear+     in hledger's output.  This can be used to match postings generated+     "just now", rather than generated in the past and saved to the+     journal.++   Also, any transaction that has been changed by auto posting rules+will have these tags added:++   * 'modified:' - this transaction was modified+   * '_modified:' - a hidden tag not appearing in the comment; this+     transaction was modified "just now".+++File: hledger.info,  Node: CSV FORMAT,  Next: TIMECLOCK FORMAT,  Prev: JOURNAL FORMAT,  Up: Top++13 CSV FORMAT+*************++How hledger reads CSV data, and the CSV rules file format.++   hledger can read CSV files (Character Separated Value - usually+comma, semicolon, or tab) containing dated records as if they were+journal files, automatically converting each CSV record into a+transaction.++   (To learn about _writing_ CSV, see CSV output.)++   We describe each CSV file's format with a corresponding _rules file_.+By default this is named like the CSV file with a '.rules' extension+added.  Eg when reading 'FILE.csv', hledger also looks for+'FILE.csv.rules' in the same directory as 'FILE.csv'.  You can specify a+different rules file with the '--rules-file' option.  If a rules file is+not found, hledger will create a sample rules file, which you'll need to+adjust.++   This file contains rules describing the CSV data (header line, fields+layout, date format etc.), and how to construct hledger journal entries+(transactions) from it.  Often there will also be a list of conditional+rules for categorising transactions based on their descriptions.  Here's+an overview of the CSV rules; these are described more fully below,+after the examples:++*'skip'*                    skip one or more header lines or matched+                            CSV records+*'fields' list*             name CSV fields, assign them to hledger+                            fields+*field assignment*          assign a value to one hledger field, with+                            interpolation+*Field names*               hledger field names, used in the fields+                            list and field assignments+*'separator'*               a custom field separator+*'if' block*                apply some rules to CSV records matched by+                            patterns+*'if' table*                apply some rules to CSV records matched by+                            patterns, alternate syntax+*'end'*                     skip the remaining CSV records+*'date-format'*             how to parse dates in CSV records+*'decimal-mark'*            the decimal mark used in CSV amounts, if+                            ambiguous+*'newest-first'*            disambiguate record order when there's only+                            one date+*'include'*                 inline another CSV rules file+*'balance-type'*            choose which type of balance assignments to+                            use++   Note, for best error messages when reading CSV files, use a '.csv',+'.tsv' or '.ssv' file extension or file prefix - see File Extension+below.++   There's an introductory Convert CSV files tutorial on hledger.org.++* Menu:++* Examples::+* CSV rules::+* Tips::+++File: hledger.info,  Node: Examples,  Next: CSV rules,  Up: CSV FORMAT++13.1 Examples+=============++Here are some sample hledger CSV rules files.  See also the full+collection at:+https://github.com/simonmichael/hledger/tree/master/examples/csv++* Menu:++* Basic::+* Bank of Ireland::+* Amazon::+* Paypal::+++File: hledger.info,  Node: Basic,  Next: Bank of Ireland,  Up: Examples++13.1.1 Basic+------------++At minimum, the rules file must identify the date and amount fields, and+often it also specifies the date format and how many header lines there+are.  Here's a simple CSV file and a rules file for it:++Date, Description, Id, Amount+12/11/2019, Foo, 123, 10.23++# basic.csv.rules+skip         1+fields       date, description, _, amount+date-format  %d/%m/%Y++$ hledger print -f basic.csv+2019-11-12 Foo+    expenses:unknown           10.23+    income:unknown            -10.23++   Default account names are chosen, since we didn't set them.+++File: hledger.info,  Node: Bank of Ireland,  Next: Amazon,  Prev: Basic,  Up: Examples++13.1.2 Bank of Ireland+----------------------++Here's a CSV with two amount fields (Debit and Credit), and a balance+field, which we can use to add balance assertions, which is not+necessary but provides extra error checking:++Date,Details,Debit,Credit,Balance+07/12/2012,LODGMENT       529898,,10.0,131.21+07/12/2012,PAYMENT,5,,126++# bankofireland-checking.csv.rules++# skip the header line+skip++# name the csv fields, and assign some of them as journal entry fields+fields  date, description, amount-out, amount-in, balance++# We generate balance assertions by assigning to "balance"+# above, but you may sometimes need to remove these because:+#+# - the CSV balance differs from the true balance,+#   by up to 0.0000000000005 in my experience+#+# - it is sometimes calculated based on non-chronological ordering,+#   eg when multiple transactions clear on the same day++# date is in UK/Ireland format+date-format  %d/%m/%Y++# set the currency+currency  EUR++# set the base account for all txns+account1  assets:bank:boi:checking++$ hledger -f bankofireland-checking.csv print+2012-12-07 LODGMENT       529898+    assets:bank:boi:checking         EUR10.0 = EUR131.2+    income:unknown                  EUR-10.0++2012-12-07 PAYMENT+    assets:bank:boi:checking         EUR-5.0 = EUR126.0+    expenses:unknown                  EUR5.0++   The balance assertions don't raise an error above, because we're+reading directly from CSV, but they will be checked if these entries are+imported into a journal file.+++File: hledger.info,  Node: Amazon,  Next: Paypal,  Prev: Bank of Ireland,  Up: Examples++13.1.3 Amazon+-------------++Here we convert amazon.com order history, and use an if block to+generate a third posting if there's a fee.  (In practice you'd probably+get this data from your bank instead, but it's an example.)++"Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID"+"Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL"+"Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL"++# amazon-orders.csv.rules++# skip one header line+skip 1++# name the csv fields, and assign the transaction's date, amount and code.+# Avoided the "status" and "amount" hledger field names to prevent confusion.+fields date, _, toorfrom, name, amzstatus, amzamount, fees, code++# how to parse the date+date-format %b %-d, %Y++# combine two fields to make the description+description %toorfrom %name++# save the status as a tag+comment     status:%amzstatus++# set the base account for all transactions+account1    assets:amazon+# leave amount1 blank so it can balance the other(s).+# I'm assuming amzamount excludes the fees, don't remember++# set a generic account2+account2    expenses:misc+amount2     %amzamount+# and maybe refine it further:+#include categorisation.rules++# add a third posting for fees, but only if they are non-zero.+if %fees [1-9]+ account3    expenses:fees+ amount3     %fees++$ hledger -f amazon-orders.csv print+2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo.  ; status:Completed+    assets:amazon+    expenses:misc          $20.00++2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc.  ; status:Completed+    assets:amazon+    expenses:misc          $25.00+    expenses:fees           $1.00+++File: hledger.info,  Node: Paypal,  Prev: Amazon,  Up: Examples++13.1.4 Paypal+-------------++Here's a real-world rules file for (customised) Paypal CSV, with some+Paypal-specific rules, and a second rules file included:++"Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"+"10/01/2019","03:46:20","PDT","Calm Radio","Subscription Payment","Completed","USD","-6.99","0.00","-6.99","simon@joyful.com","memberships@calmradio.com","60P57143A8206782E","MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month","","I-R8YLY094FJYR","","-6.99",""+"10/01/2019","03:46:20","PDT","","Bank Deposit to PP Account ","Pending","USD","6.99","0.00","6.99","","simon@joyful.com","0TU1544T080463733","","","60P57143A8206782E","","0.00",""+"10/01/2019","08:57:01","PDT","Patreon","PreApproved Payment Bill User Payment","Completed","USD","-7.00","0.00","-7.00","simon@joyful.com","support@patreon.com","2722394R5F586712G","Patreon* Membership","","B-0PG93074E7M86381M","","-7.00",""+"10/01/2019","08:57:01","PDT","","Bank Deposit to PP Account ","Pending","USD","7.00","0.00","7.00","","simon@joyful.com","71854087RG994194F","Patreon* Membership","","2722394R5F586712G","","0.00",""+"10/19/2019","03:02:12","PDT","Wikimedia Foundation, Inc.","Subscription Payment","Completed","USD","-2.00","0.00","-2.00","simon@joyful.com","tle@wikimedia.org","K9U43044RY432050M","Monthly donation to the Wikimedia Foundation","","I-R5C3YUS3285L","","-2.00",""+"10/19/2019","03:02:12","PDT","","Bank Deposit to PP Account ","Pending","USD","2.00","0.00","2.00","","simon@joyful.com","3XJ107139A851061F","","","K9U43044RY432050M","","0.00",""+"10/22/2019","05:07:06","PDT","Noble Benefactor","Subscription Payment","Completed","USD","10.00","-0.59","9.41","noble@bene.fac.tor","simon@joyful.com","6L8L1662YP1334033","Joyful Systems","","I-KC9VBGY2GWDB","","9.41",""++# paypal-custom.csv.rules++# Tips:+# Export from Activity -> Statements -> Custom -> Activity download+# Suggested transaction type: "Balance affecting"+# Paypal's default fields in 2018 were:+# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Shipping Address","Address Status","Item Title","Item ID","Shipping and Handling Amount","Insurance Amount","Sales Tax","Option 1 Name","Option 1 Value","Option 2 Name","Option 2 Value","Reference Txn ID","Invoice Number","Custom Number","Quantity","Receipt ID","Balance","Address Line 1","Address Line 2/District/Neighborhood","Town/City","State/Province/Region/County/Territory/Prefecture/Republic","Zip/Postal Code","Country","Contact Phone Number","Subject","Note","Country Code","Balance Impact"+# This rules file assumes the following more detailed fields, configured in "Customize report fields":+# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"++fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note++skip  1++date-format  %-m/%-d/%Y++# ignore some paypal events+if+In Progress+Temporary Hold+Update to+ skip++# add more fields to the description+description %description_ %itemtitle++# save some other fields as tags+comment  itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_++# convert to short currency symbols+if %currency USD+ currency $+if %currency EUR+ currency E+if %currency GBP+ currency P++# generate postings++# the first posting will be the money leaving/entering my paypal account+# (negative means leaving my account, in all amount fields)+account1 assets:online:paypal+amount1  %netamount++# the second posting will be money sent to/received from other party+# (account2 is set below)+amount2  -%grossamount++# if there's a fee, add a third posting for the money taken by paypal.+if %feeamount [1-9]+ account3 expenses:banking:paypal+ amount3  -%feeamount+ comment3 business:++# choose an account for the second posting++# override the default account names:+# if the amount is positive, it's income (a debit)+if %grossamount ^[^-]+ account2 income:unknown+# if negative, it's an expense (a credit)+if %grossamount ^-+ account2 expenses:unknown++# apply common rules for setting account2 & other tweaks+include common.rules++# apply some overrides specific to this csv++# Transfers from/to bank. These are usually marked Pending,+# which can be disregarded in this case.+if+Bank Account+Bank Deposit to PP Account+ description %type for %referencetxnid %itemtitle+ account2 assets:bank:wf:pchecking+ account1 assets:online:paypal++# Currency conversions+if Currency Conversion+ account2 equity:currency conversion++# common.rules++if+darcs+noble benefactor+ account2 revenues:foss donations:darcshub+ comment2 business:++if+Calm Radio+ account2 expenses:online:apps++if+electronic frontier foundation+Patreon+wikimedia+Advent of Code+ account2 expenses:dues++if Google+ account2 expenses:online:apps+ description google | music++$ hledger -f paypal-custom.csv  print+2019-10-01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month  ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed+    assets:online:paypal          $-6.99 = $-6.99+    expenses:online:apps           $6.99++2019-10-01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E  ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending+    assets:online:paypal               $6.99 = $0.00+    assets:bank:wf:pchecking          $-6.99++2019-10-01 (2722394R5F586712G) Patreon Patreon* Membership  ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed+    assets:online:paypal          $-7.00 = $-7.00+    expenses:dues                  $7.00++2019-10-01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership  ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending+    assets:online:paypal               $7.00 = $0.00+    assets:bank:wf:pchecking          $-7.00++2019-10-19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation  ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed+    assets:online:paypal             $-2.00 = $-2.00+    expenses:dues                     $2.00+    expenses:banking:paypal      ; business:++2019-10-19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M  ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending+    assets:online:paypal               $2.00 = $0.00+    assets:bank:wf:pchecking          $-2.00++2019-10-22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems  ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed+    assets:online:paypal                       $9.41 = $9.41+    revenues:foss donations:darcshub         $-10.00  ; business:+    expenses:banking:paypal                    $0.59  ; business:+++File: hledger.info,  Node: CSV rules,  Next: Tips,  Prev: Examples,  Up: CSV FORMAT++13.2 CSV rules+==============++The following kinds of rule can appear in the rules file, in any order.+Blank lines and lines beginning with '#' or ';' are ignored.++* Menu:++* skip::+* fields list::+* field assignment::+* Field names::+* separator::+* if block::+* if table::+* end::+* date-format::+* decimal-mark::+* newest-first::+* include::+* balance-type::+++File: hledger.info,  Node: skip,  Next: fields list,  Up: CSV rules++13.2.1 'skip'+-------------++skip N++   The word "skip" followed by a number (or no number, meaning 1) tells+hledger to ignore this many non-empty lines preceding the CSV data.+(Empty/blank lines are skipped automatically.)  You'll need this+whenever your CSV data contains header lines.++   It also has a second purpose: it can be used inside if blocks to+ignore certain CSV records (described below).+++File: hledger.info,  Node: fields list,  Next: field assignment,  Prev: skip,  Up: CSV rules++13.2.2 'fields' list+--------------------++fields FIELDNAME1, FIELDNAME2, ...++   A fields list (the word "fields" followed by comma-separated field+names) is the quick way to assign CSV field values to hledger fields.+(The other way is field assignments, see below.)  A fields list does+does two things:++  1. It names the CSV fields.  This is optional, but can be convenient+     later for interpolating them.++  2. Whenever you use a standard hledger field name (defined below), the+     CSV value is assigned to that part of the hledger transaction.++   Here's an example that says "use the 1st, 2nd and 4th fields as the+transaction's date, description and amount; name the last two fields for+later reference; and ignore the others":++fields date, description, , amount, , , somefield, anotherfield++   Tips:++   * The fields list always use commas, even if your CSV data uses+     another separator character.+   * Currently there must be least two items in the list (at least one+     comma).+   * Field names may not contain spaces.  Spaces before/after field+     names are optional.+   * Field names may contain '_' (underscore) or '-' (hyphen).+   * If the CSV contains column headings, it's a good idea to use these,+     suitably modified, as the basis for your field names (eg+     lower-cased, with underscores instead of spaces).+   * If some heading names match standard hledger fields, but you don't+     want to set the hledger fields directly, alter those names, eg by+     appending an underscore.+   * Fields you don't care about can be given a dummy name (eg: '_' ),+     or no name.+++File: hledger.info,  Node: field assignment,  Next: Field names,  Prev: fields list,  Up: CSV rules++13.2.3 field assignment+-----------------------++HLEDGERFIELDNAME FIELDVALUE++   Field assignments are the more flexible way to assign CSV values to+hledger fields.  They can be used instead of or in addition to a fields+list (see above).++   To assign a value to a hledger field, write the field name (any of+the standard hledger field/pseudo-field names, defined below), a space,+followed by a text value on the same line.  This text value may+interpolate CSV fields, referenced by their 1-based position in the CSV+record ('%N'), or by the name they were given in the fields list+('%CSVFIELDNAME').++   Some examples:++# set the amount to the 4th CSV field, with " USD" appended+amount %4 USD++# combine three fields to make a comment, containing note: and date: tags+comment note: %somefield - %anotherfield, date: %1++   Tips:++   * Interpolation strips outer whitespace (so a CSV value like '" 1 "'+     becomes '1' when interpolated) (#1051).+   * Interpolations always refer to a CSV field - you can't interpolate+     a hledger field.  (See Referencing other fields below).+++File: hledger.info,  Node: Field names,  Next: separator,  Prev: field assignment,  Up: CSV rules++13.2.4 Field names+------------------++Here are the standard hledger field (and pseudo-field) names, which you+can use in a fields list and in field assignments.  For more about the+transaction parts they refer to, see Transactions.++* Menu:++* date field::+* date2 field::+* status field::+* code field::+* description field::+* comment field::+* account field::+* amount field::+* currency field::+* balance field::+++File: hledger.info,  Node: date field,  Next: date2 field,  Up: Field names++13.2.4.1 date field+...................++Assigning to 'date' sets the transaction date.+++File: hledger.info,  Node: date2 field,  Next: status field,  Prev: date field,  Up: Field names++13.2.4.2 date2 field+....................++'date2' sets the transaction's secondary date, if any.+++File: hledger.info,  Node: status field,  Next: code field,  Prev: date2 field,  Up: Field names++13.2.4.3 status field+.....................++'status' sets the transaction's status, if any.+++File: hledger.info,  Node: code field,  Next: description field,  Prev: status field,  Up: Field names++13.2.4.4 code field+...................++'code' sets the transaction's code, if any.+++File: hledger.info,  Node: description field,  Next: comment field,  Prev: code field,  Up: Field names++13.2.4.5 description field+..........................++'description' sets the transaction's description, if any.+++File: hledger.info,  Node: comment field,  Next: account field,  Prev: description field,  Up: Field names++13.2.4.6 comment field+......................++'comment' sets the transaction's comment, if any.++   'commentN', where N is a number, sets the Nth posting's comment.++   Tips:++   * You can assign multi-line comments by writing literal '\n' in the+     code.  A comment starting with '\n' will begin on a new line.+   * Comments can contain tags, as usual.+++File: hledger.info,  Node: account field,  Next: amount field,  Prev: comment field,  Up: Field names++13.2.4.7 account field+......................++Assigning to 'accountN', where N is 1 to 99, sets the account name of+the Nth posting, and causes that posting to be generated.++   Most often there are two postings, so you'll want to set 'account1'+and 'account2'.  Typically 'account1' is associated with the CSV file,+and is set once with a top-level assignment, while 'account2' is set+based on each transaction's description, and in conditional blocks.++   If a posting's account name is left unset but its amount is set (see+below), a default account name will be chosen (like "expenses:unknown"+or "income:unknown").+++File: hledger.info,  Node: amount field,  Next: currency field,  Prev: account field,  Up: Field names++13.2.4.8 amount field+.....................++'amountN' sets the amount of the Nth posting, and causes that posting to+be generated.  By assigning to 'amount1', 'amount2', ...  etc.  you can+generate up to 99 postings.++   'amountN-in' and 'amountN-out' can be used instead, if the CSV uses+separate fields for debits and credits (inflows and outflows).  hledger+assumes both of these CSV fields are unsigned, and will automatically+negate the "-out" value.  If they are signed, see "Setting amounts"+below.++   'amount', or 'amount-in' and 'amount-out' are a legacy mode, to keep+pre-hledger-1.17 CSV rules files working (and for occasional+convenience).  They are suitable only for two-posting transactions; they+set both posting 1's and posting 2's amount.  Posting 2's amount will be+negated, and also converted to cost if there's a transaction price.++   If you have an existing rules file using the unnumbered form, you+might want to use the numbered form in certain conditional blocks,+without having to update and retest all the old rules.  To facilitate+this, posting 1 ignores 'amount'/'amount-in'/'amount-out' if any of+'amount1'/'amount1-in'/'amount1-out' are assigned, and posting 2 ignores+them if any of 'amount2'/'amount2-in'/'amount2-out' are assigned,+avoiding conflicts.+++File: hledger.info,  Node: currency field,  Next: balance field,  Prev: amount field,  Up: Field names++13.2.4.9 currency field+.......................++'currency' sets a currency symbol, to be prepended to all postings'+amounts.  You can use this if the CSV amounts do not have a currency+symbol, eg if it is in a separate column.++   'currencyN' prepends a currency symbol to just the Nth posting's+amount.+++File: hledger.info,  Node: balance field,  Prev: currency field,  Up: Field names++13.2.4.10 balance field+.......................++'balanceN' sets a balance assertion amount (or if the posting amount is+left empty, a balance assignment) on posting N.++   'balance' is a compatibility spelling for hledger <1.17; it is+equivalent to 'balance1'.++   You can adjust the type of assertion/assignment with the+'balance-type' rule (see below).++   See Tips below for more about setting amounts and currency.+++File: hledger.info,  Node: separator,  Next: if block,  Prev: Field names,  Up: CSV rules++13.2.5 'separator'+------------------++You can use the 'separator' rule to read other kinds of+character-separated data.  The argument is any single separator+character, or the words 'tab' or 'space' (case insensitive).  Eg, for+comma-separated values (CSV):++separator ,++   or for semicolon-separated values (SSV):++separator ;++   or for tab-separated values (TSV):++separator TAB++   If the input file has a '.csv', '.ssv' or '.tsv' file extension (or a+'csv:', 'ssv:', 'tsv:' prefix), the appropriate separator will be+inferred automatically, and you won't need this rule.+++File: hledger.info,  Node: if block,  Next: if table,  Prev: separator,  Up: CSV rules++13.2.6 'if' block+-----------------++if MATCHER+ RULE++if+MATCHER+MATCHER+MATCHER+ RULE+ RULE++   Conditional blocks ("if blocks") are a block of rules that are+applied only to CSV records which match certain patterns.  They are+often used for customising account names based on transaction+descriptions.++* Menu:++* Matching the whole record::+* Matching individual fields::+* Combining matchers::+* Rules applied on successful match::+++File: hledger.info,  Node: Matching the whole record,  Next: Matching individual fields,  Up: if block++13.2.6.1 Matching the whole record+..................................++Each MATCHER can be a record matcher, which looks like this:++REGEX++   REGEX is a case-insensitive regular expression that tries to match+anywhere within the CSV record.  It is a POSIX ERE (extended regular+expression) that also supports GNU word boundaries ('\b', '\B', '\<',+'\>'), and nothing else.  If you have trouble, be sure to check our doc:+https://hledger.org/hledger.html#regular-expressions++   Important note: the record that is matched is not the original+record, but a synthetic one, with any enclosing double quotes (but not+enclosing whitespace) removed, and always comma-separated (which means+that a field containing a comma will appear like two fields).  Eg, if+the original record is '2020-01-01; "Acme, Inc."; 1,000', the REGEX will+actually see '2020-01-01,Acme, Inc., 1,000').+++File: hledger.info,  Node: Matching individual fields,  Next: Combining matchers,  Prev: Matching the whole record,  Up: if block++13.2.6.2 Matching individual fields+...................................++Or, MATCHER can be a field matcher, like this:++%CSVFIELD REGEX++   which matches just the content of a particular CSV field.  CSVFIELD+is a percent sign followed by the field's name or column number, like+'%date' or '%1'.+++File: hledger.info,  Node: Combining matchers,  Next: Rules applied on successful match,  Prev: Matching individual fields,  Up: if block++13.2.6.3 Combining matchers+...........................++A single matcher can be written on the same line as the "if"; or+multiple matchers can be written on the following lines, non-indented.+Multiple matchers are OR'd (any one of them can match), unless one+begins with an '&' symbol, in which case it is AND'ed with the previous+matcher.++if+MATCHER+& MATCHER+ RULE+++File: hledger.info,  Node: Rules applied on successful match,  Prev: Combining matchers,  Up: if block++13.2.6.4 Rules applied on successful match+..........................................++After the patterns there should be one or more rules to apply, all+indented by at least one space.  Three kinds of rule are allowed in+conditional blocks:++   * field assignments (to set a hledger field)+   * skip (to skip the matched CSV record)+   * end (to skip all remaining CSV records).++   Examples:++# if the CSV record contains "groceries", set account2 to "expenses:groceries"+if groceries+ account2 expenses:groceries++# if the CSV record contains any of these patterns, set account2 and comment as shown+if+monthly service fee+atm transaction fee+banking thru software+ account2 expenses:business:banking+ comment  XXX deductible ? check it+++File: hledger.info,  Node: if table,  Next: end,  Prev: if block,  Up: CSV rules++13.2.7 'if' table+-----------------++if,CSVFIELDNAME1,CSVFIELDNAME2,...,CSVFIELDNAMEn+MATCHER1,VALUE11,VALUE12,...,VALUE1n+MATCHER2,VALUE21,VALUE22,...,VALUE2n+MATCHER3,VALUE31,VALUE32,...,VALUE3n+<empty line>++   Conditional tables ("if tables") are a different syntax to specify+field assignments that will be applied only to CSV records which match+certain patterns.++   MATCHER could be either field or record matcher, as described above.+When MATCHER matches, values from that row would be assigned to the CSV+fields named on the 'if' line, in the same order.++   Therefore 'if' table is exactly equivalent to a sequence of of 'if'+blocks:++if MATCHER1+  CSVFIELDNAME1 VALUE11+  CSVFIELDNAME2 VALUE12+  ...+  CSVFIELDNAMEn VALUE1n++if MATCHER2+  CSVFIELDNAME1 VALUE21+  CSVFIELDNAME2 VALUE22+  ...+  CSVFIELDNAMEn VALUE2n++if MATCHER3+  CSVFIELDNAME1 VALUE31+  CSVFIELDNAME2 VALUE32+  ...+  CSVFIELDNAMEn VALUE3n++   Each line starting with MATCHER should contain enough (possibly+empty) values for all the listed fields.++   Rules would be checked and applied in the order they are listed in+the table and, like with 'if' blocks, later rules (in the same or+another table) or 'if' blocks could override the effect of any rule.++   Instead of ',' you can use a variety of other non-alphanumeric+characters as a separator.  First character after 'if' is taken to be+the separator for the rest of the table.  It is the responsibility of+the user to ensure that separator does not occur inside MATCHERs and+values - there is no way to escape separator.++   Example:++if,account2,comment+atm transaction fee,expenses:business:banking,deductible? check it+%description groceries,expenses:groceries,+2020/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out+++File: hledger.info,  Node: end,  Next: date-format,  Prev: if table,  Up: CSV rules++13.2.8 'end'+------------++This rule can be used inside if blocks (only), to make hledger stop+reading this CSV file and move on to the next input file, or to command+execution.  Eg:++# ignore everything following the first empty record+if ,,,,+ end+++File: hledger.info,  Node: date-format,  Next: decimal-mark,  Prev: end,  Up: CSV rules++13.2.9 'date-format'+--------------------++date-format DATEFMT++   This is a helper for the 'date' (and 'date2') fields.  If your CSV+dates are not formatted like 'YYYY-MM-DD', 'YYYY/MM/DD' or 'YYYY.MM.DD',+you'll need to add a date-format rule describing them with a strptime+date parsing pattern, which must parse the CSV date value completely.+Some examples:++# MM/DD/YY+date-format %m/%d/%y++# D/M/YYYY+# The - makes leading zeros optional.+date-format %-d/%-m/%Y++# YYYY-Mmm-DD+date-format %Y-%h-%d++# M/D/YYYY HH:MM AM some other junk+# Note the time and junk must be fully parsed, though only the date is used.+date-format %-m/%-d/%Y %l:%M %p some other junk++   For the supported strptime syntax, see:+https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime++   Note that although you can parse date-times which include a time+zone, that time zone is ignored; it will not change the date that is+parsed.  This means when reading CSV data with times not in your local+time zone, dates can be "off by one".+++File: hledger.info,  Node: decimal-mark,  Next: newest-first,  Prev: date-format,  Up: CSV rules++13.2.10 'decimal-mark'+----------------------++decimal-mark .++   or:++decimal-mark ,++   hledger automatically accepts either period or comma as a decimal+mark when parsing numbers (cf Amounts).  However if any numbers in the+CSV contain digit group marks, such as thousand-separating commas, you+should declare the decimal mark explicitly with this rule, to avoid+misparsed numbers.+++File: hledger.info,  Node: newest-first,  Next: include,  Prev: decimal-mark,  Up: CSV rules++13.2.11 'newest-first'+----------------------++hledger always sorts the generated transactions by date.  Transactions+on the same date should appear in the same order as their CSV records,+as hledger can usually auto-detect whether the CSV's normal order is+oldest first or newest first.  But if all of the following are true:++   * the CSV might sometimes contain just one day of data (all records+     having the same date)+   * the CSV records are normally in reverse chronological order (newest+     at the top)+   * and you care about preserving the order of same-day transactions++   then, you should add the 'newest-first' rule as a hint.  Eg:++# tell hledger explicitly that the CSV is normally newest first+newest-first+++File: hledger.info,  Node: include,  Next: balance-type,  Prev: newest-first,  Up: CSV rules++13.2.12 'include'+-----------------++include RULESFILE++   This includes the contents of another CSV rules file at this point.+'RULESFILE' is an absolute file path or a path relative to the current+file's directory.  This can be useful for sharing common rules between+several rules files, eg:++# someaccount.csv.rules++## someaccount-specific rules+fields   date,description,amount+account1 assets:someaccount+account2 expenses:misc++## common rules+include categorisation.rules+++File: hledger.info,  Node: balance-type,  Prev: include,  Up: CSV rules++13.2.13 'balance-type'+----------------------++Balance assertions generated by assigning to balanceN are of the simple+'=' type by default, which is a single-commodity, subaccount-excluding+assertion.  You may find the subaccount-including variants more useful,+eg if you have created some virtual subaccounts of checking to help with+budgeting.  You can select a different type of assertion with the+'balance-type' rule:++# balance assertions will consider all commodities and all subaccounts+balance-type ==*++   Here are the balance assertion types for quick reference:++=    single commodity, exclude subaccounts+=*   single commodity, include subaccounts+==   multi commodity,  exclude subaccounts+==*  multi commodity,  include subaccounts+++File: hledger.info,  Node: Tips,  Prev: CSV rules,  Up: CSV FORMAT++13.3 Tips+=========++* Menu:++* Rapid feedback::+* Valid CSV::+* File Extension::+* Reading multiple CSV files::+* Valid transactions::+* Deduplicating importing::+* Setting amounts::+* Amount signs::+* Setting currency/commodity::+* Amount decimal places::+* Referencing other fields::+* How CSV rules are evaluated::+++File: hledger.info,  Node: Rapid feedback,  Next: Valid CSV,  Up: Tips++13.3.1 Rapid feedback+---------------------++It's a good idea to get rapid feedback while creating/troubleshooting+CSV rules.  Here's a good way, using entr from eradman.com/entrproject:++$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC'++   A desc: query (eg) is used to select just one, or a few, transactions+of interest.  "bash -c" is used to run multiple commands, so we can echo+a separator each time the command re-runs, making it easier to read the+output.+++File: hledger.info,  Node: Valid CSV,  Next: File Extension,  Prev: Rapid feedback,  Up: Tips++13.3.2 Valid CSV+----------------++hledger accepts CSV conforming to RFC 4180.  When CSV values are+enclosed in quotes, note:++   * they must be double quotes (not single quotes)+   * spaces outside the quotes are not allowed+++File: hledger.info,  Node: File Extension,  Next: Reading multiple CSV files,  Prev: Valid CSV,  Up: Tips++13.3.3 File Extension+---------------------++To help hledger identify the format and show the right error messages,+CSV/SSV/TSV files should normally be named with a '.csv', '.ssv' or+'.tsv' filename extension.  Or, the file path should be prefixed with+'csv:', 'ssv:' or 'tsv:'.  Eg:++$ hledger -f foo.ssv print++   or:++$ cat foo | hledger -f ssv:- foo++   You can override the file extension with a separator rule if needed.+See also: Input files in the hledger manual.+++File: hledger.info,  Node: Reading multiple CSV files,  Next: Valid transactions,  Prev: File Extension,  Up: Tips++13.3.4 Reading multiple CSV files+---------------------------------++If you use multiple '-f' options to read multiple CSV files at once,+hledger will look for a correspondingly-named rules file for each CSV+file.  But if you use the '--rules-file' option, that rules file will be+used for all the CSV files.+++File: hledger.info,  Node: Valid transactions,  Next: Deduplicating importing,  Prev: Reading multiple CSV files,  Up: Tips++13.3.5 Valid transactions+-------------------------++After reading a CSV file, hledger post-processes and validates the+generated journal entries as it would for a journal file - balancing+them, applying balance assignments, and canonicalising amount styles.+Any errors at this stage will be reported in the usual way, displaying+the problem entry.++   There is one exception: balance assertions, if you have generated+them, will not be checked, since normally these will work only when the+CSV data is part of the main journal.  If you do need to check balance+assertions generated from CSV right away, pipe into another hledger:++$ hledger -f file.csv print | hledger -f- print+++File: hledger.info,  Node: Deduplicating importing,  Next: Setting amounts,  Prev: Valid transactions,  Up: Tips++13.3.6 Deduplicating, importing+-------------------------------++When you download a CSV file periodically, eg to get your latest bank+transactions, the new file may overlap with the old one, containing some+of the same records.++   The import command will (a) detect the new transactions, and (b)+append just those transactions to your main journal.  It is idempotent,+so you don't have to remember how many times you ran it or with which+version of the CSV. (It keeps state in a hidden '.latest.FILE.csv'+file.)  This is the easiest way to import CSV data.  Eg:++# download the latest CSV files, then run this command.+# Note, no -f flags needed here.+$ hledger import *.csv [--dry]++   This method works for most CSV files.  (Where records have a stable+chronological order, and new records appear only at the new end.)++   A number of other tools and workflows, hledger-specific and+otherwise, exist for converting, deduplicating, classifying and managing+CSV data.  See:++   * https://hledger.org -> sidebar -> real world setups+   * https://plaintextaccounting.org -> data import/conversion+++File: hledger.info,  Node: Setting amounts,  Next: Amount signs,  Prev: Deduplicating importing,  Up: Tips++13.3.7 Setting amounts+----------------------++Some tips on using the amount-setting rules discussed above.++   Here are the ways to set a posting's amount:++  1. *If the CSV has a single amount field:*+     Assign (via a fields list or a field assignment) to 'amountN'.+     This sets the Nth posting's amount.  N is usually 1 or 2 but can go+     up to 99.++  2. *If the CSV has separate amount fields for debit & credit (in &+     out):*++       a. *If both fields are unsigned:*+          Assign to 'amountN-in' and 'amountN-out'.  This sets posting+          N's amount to whichever of these has a non-zero value, and+          negates the "-out" value.++       b. *If either field is signed (can contain a minus sign):*+          Use a conditional rule to flip the sign (of non-empty values).+          Since hledger always negates amountN-out, if it was already+          negative, we must undo that by negating once more (but only if+          the field is non-empty):++     fields date, description, amount1-in, amount1-out+     if %amount1-out [1-9]+      amount1-out -%amount1-out++       c. *If both fields, or neither field, can contain a non-zero+          value:*+          hledger normally expects exactly one of the fields to have a+          non-zero value.  Eg, the 'amountN-in'/'amountN-out' rules+          would reject value pairs like these:++     "",  ""+     "0", "0"+     "1", "none"++     So, use smarter conditional rules to set the amount from the+     appropriate field.  Eg, these rules would make it use only the+     value containing non-zero digits, handling the above:++     fields date, description, in, out+     if %in [1-9]+      amount1 %in+     if %out [1-9]+      amount1 %out++  3. *If you want posting 2's amount converted to cost:*+     Assign to 'amount' (or to 'amount-in' and 'amount-out').  (This is+     the legacy numberless syntax, which sets amount1 and amount2 and+     converts amount2 to cost.)++  4. *If the CSV has the balance instead of the transaction amount:*+     Assign to 'balanceN', which sets posting N's amount indirectly via+     a balance assignment.  (Old syntax: 'balance', equivalent to+     'balance1'.)++        * *If hledger guesses the wrong default account name:*+          When setting the amount via balance assertion, hledger may+          guess the wrong default account name.  So, set the account+          name explicitly, eg:++          fields date, description, balance1+          account1 assets:checking+++File: hledger.info,  Node: Amount signs,  Next: Setting currency/commodity,  Prev: Setting amounts,  Up: Tips++13.3.8 Amount signs+-------------------++There is some special handling for amount signs, to simplify parsing and+sign-flipping:++   * *If an amount value begins with a plus sign:*+     that will be removed: '+AMT' becomes 'AMT'++   * *If an amount value is parenthesised:*+     it will be de-parenthesised and sign-flipped: '(AMT)' becomes+     '-AMT'++   * *If an amount value has two minus signs (or two sets of+     parentheses, or a minus sign and parentheses):*+     they cancel out and will be removed: '--AMT' or '-(AMT)' becomes+     'AMT'++   * *If an amount value contains just a sign (or just a set of+     parentheses):*+     that is removed, making it an empty value.  '"+"' or '"-"' or+     '"()"' becomes '""'.+++File: hledger.info,  Node: Setting currency/commodity,  Next: Amount decimal places,  Prev: Amount signs,  Up: Tips++13.3.9 Setting currency/commodity+---------------------------------++If the currency/commodity symbol is included in the CSV's amount+field(s):++2020-01-01,foo,$123.00++   you don't have to do anything special for the commodity symbol, it+will be assigned as part of the amount.  Eg:++fields date,description,amount++2020-01-01 foo+    expenses:unknown         $123.00+    income:unknown          $-123.00++   If the currency is provided as a separate CSV field:++2020-01-01,foo,USD,123.00++   You can assign that to the 'currency' pseudo-field, which has the+special effect of prepending itself to every amount in the transaction+(on the left, with no separating space):++fields date,description,currency,amount++2020-01-01 foo+    expenses:unknown       USD123.00+    income:unknown        USD-123.00++   Or, you can use a field assignment to construct the amount yourself,+with more control.  Eg to put the symbol on the right, and separated by+a space:++fields date,description,cur,amt+amount %amt %cur++2020-01-01 foo+    expenses:unknown        123.00 USD+    income:unknown         -123.00 USD++   Note we used a temporary field name ('cur') that is not 'currency' -+that would trigger the prepending effect, which we don't want here.+++File: hledger.info,  Node: Amount decimal places,  Next: Referencing other fields,  Prev: Setting currency/commodity,  Up: Tips++13.3.10 Amount decimal places+-----------------------------++Like amounts in a journal file, the amounts generated by CSV rules like+'amount1' influence commodity display styles, such as the number of+decimal places displayed in reports.++   The original amounts as written in the CSV file do not affect display+style (because we don't yet reliably know their commodity).+++File: hledger.info,  Node: Referencing other fields,  Next: How CSV rules are evaluated,  Prev: Amount decimal places,  Up: Tips++13.3.11 Referencing other fields+--------------------------------++In field assignments, you can interpolate only CSV fields, not hledger+fields.  In the example below, there's both a CSV field and a hledger+field named amount1, but %amount1 always means the CSV field, not the+hledger field:++# Name the third CSV field "amount1"+fields date,description,amount1++# Set hledger's amount1 to the CSV amount1 field followed by USD+amount1 %amount1 USD++# Set comment to the CSV amount1 (not the amount1 assigned above)+comment %amount1++   Here, since there's no CSV amount1 field, %amount1 will produce a+literal "amount1":++fields date,description,csvamount+amount1 %csvamount USD+# Can't interpolate amount1 here+comment %amount1++   When there are multiple field assignments to the same hledger field,+only the last one takes effect.  Here, comment's value will be be B, or+C if "something" is matched, but never A:++comment A+comment B+if something+ comment C+++File: hledger.info,  Node: How CSV rules are evaluated,  Prev: Referencing other fields,  Up: Tips++13.3.12 How CSV rules are evaluated+-----------------------------------++Here's how to think of CSV rules being evaluated (if you really need+to).  First,++   * 'include' - all includes are inlined, from top to bottom, depth+     first.  (At each include point the file is inlined and scanned for+     further includes, recursively, before proceeding.)++   Then "global" rules are evaluated, top to bottom.  If a rule is+repeated, the last one wins:++   * 'skip' (at top level)+   * 'date-format'+   * 'newest-first'+   * 'fields' - names the CSV fields, optionally sets up initial+     assignments to hledger fields++   Then for each CSV record in turn:++   * test all 'if' blocks.  If any of them contain a 'end' rule, skip+     all remaining CSV records.  Otherwise if any of them contain a+     'skip' rule, skip that many CSV records.  If there are multiple+     matched 'skip' rules, the first one wins.+   * collect all field assignments at top level and in matched 'if'+     blocks.  When there are multiple assignments for a field, keep only+     the last one.+   * compute a value for each hledger field - either the one that was+     assigned to it (and interpolate the %CSVFIELDNAME references), or a+     default+   * generate a synthetic hledger transaction from these values.++   This is all part of the CSV reader, one of several readers hledger+can use to parse input files.  When all files have been read+successfully, the transactions are passed as input to whichever hledger+command the user specified.+++File: hledger.info,  Node: TIMECLOCK FORMAT,  Next: TIMEDOT FORMAT,  Prev: CSV FORMAT,  Up: Top++14 TIMECLOCK FORMAT+*******************++The time logging format of timeclock.el, as read by hledger.++   hledger can read time logs in timeclock format.  As with Ledger,+these are (a subset of) timeclock.el's format, containing clock-in and+clock-out entries as in the example below.  The date is a simple date.+The time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are+optional.  The timezone, if present, must be four digits and is ignored+(currently the time is always interpreted as a local time).++i 2015/03/30 09:00:00 some:account name  optional description after two spaces+o 2015/03/30 09:20:00+i 2015/03/31 22:21:45 another account+o 2015/04/01 02:00:34++   hledger treats each clock-in/clock-out pair as a transaction posting+some number of hours to an account.  Or if the session spans more than+one day, it is split into several transactions, one for each day.  For+the above time log, 'hledger print' generates these journal entries:++$ hledger -f t.timeclock print+2015-03-30 * optional description after two spaces+    (some:account name)         0.33h++2015-03-31 * 22:21-23:59+    (another account)         1.64h++2015-04-01 * 00:00-02:00+    (another account)         2.01h++   Here is a sample.timeclock to download and some queries to try:++$ hledger -f sample.timeclock balance                               # current time balances+$ hledger -f sample.timeclock register -p 2009/3                    # sessions in march 2009+$ hledger -f sample.timeclock register -p weekly --depth 1 --empty  # time summary by week++   To generate time logs, ie to clock in and clock out, you could:++   * use emacs and the built-in timeclock.el, or the extended+     timeclock-x.el and perhaps the extras in ledgerutils.el++   * at the command line, use these bash aliases: 'shell alias ti="echo+     i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o+     `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"'++   * or use the old 'ti' and 'to' scripts in the ledger 2.x repository.+     These rely on a "timeclock" executable which I think is just the+     ledger 2 executable renamed.+++File: hledger.info,  Node: TIMEDOT FORMAT,  Next: COMMON TASKS,  Prev: TIMECLOCK FORMAT,  Up: Top++15 TIMEDOT FORMAT+*****************++'timedot' format is hledger's human-friendly time logging format.+Compared to 'timeclock' format, it is++   * convenient for quick, approximate, and retroactive time logging+   * readable: you can see at a glance where time was spent.++   A timedot file contains a series of day entries, which might look+like this:++2021-08-04+hom:errands          .... ....+fos:hledger:timedot  ..         ; docs+per:admin:finance    ++   hledger reads this as three time transactions on this day, with each+dot representing a quarter-hour spent:++$ hledger -f a.timedot print   # .timedot file extension activates the timedot reader+2021-08-04 *+    (hom:errands)            2.00++2021-08-04 *+    (fos:hledger:timedot)    0.50++2021-08-04 *+    (per:admin:finance)      0++   A day entry begins with a date line:++   * a non-indented *simple date* (Y-M-D, Y/M/D, or Y.M.D).++   Optionally this can be followed on the same line by++   * a common *transaction description* for this day+   * a common *transaction comment* for this day, after a semicolon+     (';').++   After the date line are zero or more optionally-indented time+transaction lines, consisting of:++   * an *account name* - any word or phrase, usually a hledger-style+     account name.+   * *two or more spaces* - a field separator, required if there is an+     amount (as in journal format).+   * a *timedot amount* - dots representing quarter hours, or a number+     representing hours.+   * an optional *comment* beginning with semicolon.  This is ignored.++   In more detail, timedot amounts can be:++   * *dots*: zero or more period characters, each representing one+     quarter-hour.  Spaces are ignored and can be used for grouping.+     Eg: '.... ..'++   * a *number*, representing hours.  Eg: '1.5'++   * a *number immediately followed by a unit symbol* 's', 'm', 'h',+     'd', 'w', 'mo', or 'y', representing seconds, minutes, hours, days+     weeks, months or years.  Eg '1.5h' or '90m'.  The following+     equivalencies are assumed:+     '60s' = '1m', '60m' = '1h', '24h' = '1d', '7d' = '1w', '30d' =+     '1mo', '365d' = '1y'.  (This unit will not be visible in the+     generated transaction amount, which is always in hours.)++   There is some added flexibility to help with keeping time log data in+the same file as your notes, todo lists, etc.:++   * Lines beginning with '#' or ';', and blank lines, are ignored.++   * Lines not ending with a double-space and amount are parsed as+     transactions with zero amount.  (Most hledger reports hide these by+     default; add -E to see them.)++   * One or more stars ('*') followed by a space, at the start of a+     line, is ignored.  So date lines or time transaction lines can also+     be Org-mode headlines.++   * All Org-mode headlines before the first date line are ignored.++   More examples:++# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.+2016/2/1+inc:client1   .... .... .... .... .... ....+fos:haskell   .... ..+biz:research  .++2016/2/2+inc:client1   .... ....+biz:research  .++2016/2/3+inc:client1   4+fos:hledger   3+biz:research  1++* Time log+** 2020-01-01+*** adm:time  .+*** adm:finance  .++* 2020 Work Diary+** Q1+*** 2020-02-29+**** DONE+0700 yoga+**** UNPLANNED+**** BEGUN+hom:chores+ cleaning  ...+ water plants+  outdoor - one full watering can+  indoor - light watering+**** TODO+adm:planning: trip+*** LATER++   Reporting:++$ hledger -f a.timedot print date:2016/2/2+2016-02-02 *+    (inc:client1)          2.00++2016-02-02 *+    (biz:research)          0.25++$ hledger -f a.timedot bal --daily --tree+Balance changes in 2016-02-01-2016-02-03:++            ||  2016-02-01d  2016-02-02d  2016-02-03d +============++========================================+ biz        ||         0.25         0.25         1.00 +   research ||         0.25         0.25         1.00 + fos        ||         1.50            0         3.00 +   haskell  ||         1.50            0            0 +   hledger  ||            0            0         3.00 + inc        ||         6.00         2.00         4.00 +   client1  ||         6.00         2.00         4.00 +------------++----------------------------------------+            ||         7.75         2.25         8.00 ++   Using period instead of colon as account name separator:++2016/2/4+fos.hledger.timedot  4+fos.ledger           ..++$ hledger -f a.timedot --alias /\\./=: bal --tree+                4.50  fos+                4.00    hledger:timedot+                0.50    ledger+--------------------+                4.50++   A sample.timedot file.+++File: hledger.info,  Node: COMMON TASKS,  Next: LIMITATIONS,  Prev: TIMEDOT FORMAT,  Up: Top++16 COMMON TASKS+***************++Here are some quick examples of how to do some basic tasks with hledger.+For more details, see the reference section below, the+hledger_journal(5) manual, or the more extensive docs at+https://hledger.org.++* Menu:++* Getting help::+* Constructing command lines::+* Starting a journal file::+* Setting opening balances::+* Recording transactions::+* Reconciling::+* Reporting::+* Migrating to a new file::+++File: hledger.info,  Node: Getting help,  Next: Constructing command lines,  Up: COMMON TASKS++16.1 Getting help+=================++$ hledger                 # show available commands+$ hledger --help          # show common options+$ hledger CMD --help      # show common and command options, and command help+$ hledger help            # show available manuals/topics+$ hledger help hledger    # show hledger manual as info/man/text (auto-chosen)+$ hledger help journal --man  # show the journal manual as a man page+$ hledger help --help     # show more detailed help for the help command++   Find more docs, chat, mail list, reddit, issue tracker:+https://hledger.org/support.html-feedback+++File: hledger.info,  Node: Constructing command lines,  Next: Starting a journal file,  Prev: Getting help,  Up: COMMON TASKS++16.2 Constructing command lines+===============================++hledger has an extensive and powerful command line interface.  We strive+to keep it simple and ergonomic, but you may run into one of the+confusing real world details described in OPTIONS, below.  If that+happens, here are some tips that may help:++   * command-specific options must go after the command (it's fine to+     put all options there) ('hledger CMD OPTS ARGS')+   * running add-on executables directly simplifies command line parsing+     ('hledger-ui OPTS ARGS')+   * enclose "problematic" args in single quotes+   * if needed, also add a backslash to hide regular expression+     metacharacters from the shell+   * to see how a misbehaving command is being parsed, add '--debug=2'.+++File: hledger.info,  Node: Starting a journal file,  Next: Setting opening balances,  Prev: Constructing command lines,  Up: COMMON TASKS++16.3 Starting a journal file+============================++hledger looks for your accounting data in a journal file,+'$HOME/.hledger.journal' by default:++$ hledger stats+The hledger journal file "/Users/simon/.hledger.journal" was not found.+Please create it first, eg with "hledger add" or a text editor.+Or, specify an existing journal file with -f or LEDGER_FILE.++   You can override this by setting the 'LEDGER_FILE' environment+variable.  It's a good practice to keep this important file under+version control, and to start a new file each year.  So you could do+something like this:++$ mkdir ~/finance+$ cd ~/finance+$ git init+Initialized empty Git repository in /Users/simon/finance/.git/+$ touch 2020.journal+$ echo "export LEDGER_FILE=$HOME/finance/2020.journal" >> ~/.bashrc+$ source ~/.bashrc+$ hledger stats+Main file                : /Users/simon/finance/2020.journal+Included files           : +Transactions span        :  to  (0 days)+Last transaction         : none+Transactions             : 0 (0.0 per day)+Transactions last 30 days: 0 (0.0 per day)+Transactions last 7 days : 0 (0.0 per day)+Payees/descriptions      : 0+Accounts                 : 0 (depth 0)+Commodities              : 0 ()+Market prices            : 0 ()+++File: hledger.info,  Node: Setting opening balances,  Next: Recording transactions,  Prev: Starting a journal file,  Up: COMMON TASKS++16.4 Setting opening balances+=============================++Pick a starting date for which you can look up the balances of some+real-world assets (bank accounts, wallet..)  and liabilities (credit+cards..).++   To avoid a lot of data entry, you may want to start with just one or+two accounts, like your checking account or cash wallet; and pick a+recent starting date, like today or the start of the week.  You can+always come back later and add more accounts and older transactions, eg+going back to january 1st.++   Add an opening balances transaction to the journal, declaring the+balances on this date.  Here are two ways to do it:++   * The first way: open the journal in any text editor and save an+     entry like this:++     2020-01-01 * opening balances+         assets:bank:checking                $1000   = $1000+         assets:bank:savings                 $2000   = $2000+         assets:cash                          $100   = $100+         liabilities:creditcard               $-50   = $-50+         equity:opening/closing balances++     These are start-of-day balances, ie whatever was in the account at+     the end of the previous day.++     The * after the date is an optional status flag.  Here it means+     "cleared & confirmed".++     The currency symbols are optional, but usually a good idea as+     you'll be dealing with multiple currencies sooner or later.++     The = amounts are optional balance assertions, providing extra+     error checking.++   * The second way: run 'hledger add' and follow the prompts to record+     a similar transaction:++     $ hledger add+     Adding transactions to journal file /Users/simon/finance/2020.journal+     Any command line arguments will be used as defaults.+     Use tab key to complete, readline keys to edit, enter to accept defaults.+     An optional (CODE) may follow transaction dates.+     An optional ; COMMENT may follow descriptions or amounts.+     If you make a mistake, enter < at any prompt to go one step backward.+     To end a transaction, enter . when prompted.+     To quit, enter . at a date prompt or press control-d or control-c.+     Date [2020-02-07]: 2020-01-01+     Description: * opening balances+     Account 1: assets:bank:checking+     Amount  1: $1000+     Account 2: assets:bank:savings+     Amount  2 [$-1000]: $2000+     Account 3: assets:cash+     Amount  3 [$-3000]: $100+     Account 4: liabilities:creditcard+     Amount  4 [$-3100]: $-50+     Account 5: equity:opening/closing balances+     Amount  5 [$-3050]: +     Account 6 (or . or enter to finish this transaction): .+     2020-01-01 * opening balances+         assets:bank:checking                      $1000+         assets:bank:savings                       $2000+         assets:cash                                $100+         liabilities:creditcard                     $-50+         equity:opening/closing balances          $-3050+     +     Save this transaction to the journal ? [y]: +     Saved.+     Starting the next transaction (. or ctrl-D/ctrl-C to quit)+     Date [2020-01-01]: .++   If you're using version control, this could be a good time to commit+the journal.  Eg:++$ git commit -m 'initial balances' 2020.journal+++File: hledger.info,  Node: Recording transactions,  Next: Reconciling,  Prev: Setting opening balances,  Up: COMMON TASKS++16.5 Recording transactions+===========================++As you spend or receive money, you can record these transactions using+one of the methods above (text editor, hledger add) or by using the+hledger-iadd or hledger-web add-ons, or by using the import command to+convert CSV data downloaded from your bank.++   Here are some simple transactions, see the hledger_journal(5) manual+and hledger.org for more ideas:++2020/1/10 * gift received+  assets:cash   $20+  income:gifts++2020.1.12 * farmers market+  expenses:food    $13+  assets:cash++2020-01-15 paycheck+  income:salary+  assets:bank:checking    $1000+++File: hledger.info,  Node: Reconciling,  Next: Reporting,  Prev: Recording transactions,  Up: COMMON TASKS++16.6 Reconciling+================++Periodically you should reconcile - compare your hledger-reported+balances against external sources of truth, like bank statements or your+bank's website - to be sure that your ledger accurately represents the+real-world balances (and, that the real-world institutions have not made+a mistake!).  This gets easy and fast with (1) practice and (2)+frequency.  If you do it daily, it can take 2-10 minutes.  If you let it+pile up, expect it to take longer as you hunt down errors and+discrepancies.++   A typical workflow:++  1. Reconcile cash.  Count what's in your wallet.  Compare with what+     hledger reports ('hledger bal cash').  If they are different, try+     to remember the missing transaction, or look for the error in the+     already-recorded transactions.  A register report can be helpful+     ('hledger reg cash').  If you can't find the error, add an+     adjustment transaction.  Eg if you have $105 after the above, and+     can't explain the missing $2, it could be:++     2020-01-16 * adjust cash+         assets:cash    $-2 = $105+         expenses:misc++  2. Reconcile checking.  Log in to your bank's website.  Compare+     today's (cleared) balance with hledger's cleared balance ('hledger+     bal checking -C').  If they are different, track down the error or+     record the missing transaction(s) or add an adjustment transaction,+     similar to the above.  Unlike the cash case, you can usually+     compare the transaction history and running balance from your bank+     with the one reported by 'hledger reg checking -C'.  This will be+     easier if you generally record transaction dates quite similar to+     your bank's clearing dates.++  3. Repeat for other asset/liability accounts.++   Tip: instead of the register command, use hledger-ui to see a+live-updating register while you edit the journal: 'hledger-ui --watch+--register checking -C'++   After reconciling, it could be a good time to mark the reconciled+transactions' status as "cleared and confirmed", if you want to track+that, by adding the '*' marker.  Eg in the paycheck transaction above,+insert '*' between '2020-01-15' and 'paycheck'++   If you're using version control, this can be another good time to+commit:++$ git commit -m 'txns' 2020.journal+++File: hledger.info,  Node: Reporting,  Next: Migrating to a new file,  Prev: Reconciling,  Up: COMMON TASKS++16.7 Reporting+==============++Here are some basic reports.++   Show all transactions:++$ hledger print+2020-01-01 * opening balances+    assets:bank:checking                      $1000+    assets:bank:savings                       $2000+    assets:cash                                $100+    liabilities:creditcard                     $-50+    equity:opening/closing balances          $-3050++2020-01-10 * gift received+    assets:cash              $20+    income:gifts++2020-01-12 * farmers market+    expenses:food             $13+    assets:cash++2020-01-15 * paycheck+    income:salary+    assets:bank:checking           $1000++2020-01-16 * adjust cash+    assets:cash               $-2 = $105+    expenses:misc++   Show account names, and their hierarchy:++$ hledger accounts --tree+assets+  bank+    checking+    savings+  cash+equity+  opening/closing balances+expenses+  food+  misc+income+  gifts+  salary+liabilities+  creditcard++   Show all account totals:++$ hledger balance+               $4105  assets+               $4000    bank+               $2000      checking+               $2000      savings+                $105    cash+              $-3050  equity:opening/closing balances+                 $15  expenses+                 $13    food+                  $2    misc+              $-1020  income+                $-20    gifts+              $-1000    salary+                $-50  liabilities:creditcard+--------------------+                   0++   Show only asset and liability balances, as a flat list, limited to+depth 2:++$ hledger bal assets liabilities --flat -2+               $4000  assets:bank+                $105  assets:cash+                $-50  liabilities:creditcard+--------------------+               $4055++   Show the same thing without negative numbers, formatted as a simple+balance sheet:++$ hledger bs --flat -2+Balance Sheet 2020-01-16++                        || 2020-01-16 +========================++============+ Assets                 ||            +------------------------++------------+ assets:bank            ||      $4000 + assets:cash            ||       $105 +------------------------++------------+                        ||      $4105 +========================++============+ Liabilities            ||            +------------------------++------------+ liabilities:creditcard ||        $50 +------------------------++------------+                        ||        $50 +========================++============+ Net:                   ||      $4055 ++   The final total is your "net worth" on the end date.  (Or use 'bse'+for a full balance sheet with equity.)++   Show income and expense totals, formatted as an income statement:++hledger is +Income Statement 2020-01-01-2020-01-16++               || 2020-01-01-2020-01-16 +===============++=======================+ Revenues      ||                       +---------------++-----------------------+ income:gifts  ||                   $20 + income:salary ||                 $1000 +---------------++-----------------------+               ||                 $1020 +===============++=======================+ Expenses      ||                       +---------------++-----------------------+ expenses:food ||                   $13 + expenses:misc ||                    $2 +---------------++-----------------------+               ||                   $15 +===============++=======================+ Net:          ||                 $1005 ++   The final total is your net income during this period.++   Show transactions affecting your wallet, with running total:++$ hledger register cash+2020-01-01 opening balances     assets:cash                   $100          $100+2020-01-10 gift received        assets:cash                    $20          $120+2020-01-12 farmers market       assets:cash                   $-13          $107+2020-01-16 adjust cash          assets:cash                    $-2          $105++   Show weekly posting counts as a bar chart:++$ hledger activity -W+2019-12-30 *****+2020-01-06 ****+2020-01-13 ****+++File: hledger.info,  Node: Migrating to a new file,  Prev: Reporting,  Up: COMMON TASKS++16.8 Migrating to a new file+============================++At the end of the year, you may want to continue your journal in a new+file, so that old transactions don't slow down or clutter your reports,+and to help ensure the integrity of your accounting history.  See the+close command.++   If using version control, don't forget to 'git add' the new file.+++File: hledger.info,  Node: LIMITATIONS,  Next: TROUBLESHOOTING,  Prev: COMMON TASKS,  Up: Top++17 LIMITATIONS+**************++The need to precede add-on command options with '--' when invoked from+hledger is awkward.++   When input data contains non-ascii characters, a suitable system+locale must be configured (or there will be an unhelpful error).  Eg on+POSIX, set LANG to something other than C.++   In a Microsoft Windows CMD window, non-ascii characters and colours+are not supported.++   On Windows, non-ascii characters may not display correctly when+running a hledger built in CMD in MSYS/CYGWIN, or vice-versa.++   In a Cygwin/MSYS/Mintty window, the tab key is not supported in+hledger add.++   Not all of Ledger's journal file syntax is supported.  See file+format differences.++   On large data files, hledger is slower and uses more memory than+Ledger.+++File: hledger.info,  Node: TROUBLESHOOTING,  Prev: LIMITATIONS,  Up: Top++18 TROUBLESHOOTING+******************++Here are some issues you might encounter when you run hledger (and+remember you can also seek help from the IRC channel, mail list or bug+tracker):++   *Successfully installed, but "No command 'hledger' found"*+stack and cabal install binaries into a special directory, which should+be added to your PATH environment variable.  Eg on unix-like systems,+that is ~/.local/bin and ~/.cabal/bin respectively.++   *I set a custom LEDGER_FILE, but hledger is still using the default+file*+'LEDGER_FILE' should be a real environment variable, not just a shell+variable.  The command 'env | grep LEDGER_FILE' should show it.  You may+need to use 'export'.  Here's an explanation.++   *Getting errors like "Illegal byte sequence" or "Invalid or+incomplete multibyte or wide character" or "commitAndReleaseBuffer:+invalid argument (invalid character)"*+Programs compiled with GHC (hledger, haskell build tools, etc.)  need to+have a UTF-8-aware locale configured in the environment, otherwise they+will fail with these kinds of errors when they encounter non-ascii+characters.++   To fix it, set the LANG environment variable to some locale which+supports UTF-8.  The locale you choose must be installed on your system.++   Here's an example of setting LANG temporarily, on Ubuntu GNU/Linux:++$ file my.journal+my.journal: UTF-8 Unicode text         # the file is UTF8-encoded+$ echo $LANG+C                                      # LANG is set to the default locale, which does not support UTF8+$ locale -a                            # which locales are installed ?+C+en_US.utf8                             # here's a UTF8-aware one we can use+POSIX+$ LANG=en_US.utf8 hledger -f my.journal print   # ensure it is used for this command++   If available, 'C.UTF-8' will also work.  If your preferred locale+isn't listed by 'locale -a', you might need to install it.  Eg on+Ubuntu/Debian:++$ apt-get install language-pack-fr+$ locale -a+C+en_US.utf8+fr_BE.utf8+fr_CA.utf8+fr_CH.utf8+fr_FR.utf8+fr_LU.utf8+POSIX+$ LANG=fr_FR.utf8 hledger -f my.journal print++   Here's how you could set it permanently, if you use a bash shell:++$ echo "export LANG=en_US.utf8" >>~/.bash_profile+$ bash --login++   Exact spelling and capitalisation may be important.  Note the+difference on MacOS ('UTF-8', not 'utf8').  Some platforms (eg ubuntu)+allow variant spellings, but others (eg macos) require it to be exact:++$ locale -a | grep -iE en_us.*utf+en_US.UTF-8+$ LANG=en_US.UTF-8 hledger -f my.journal print+++Tag Table:+Node: Top208+Node: OPTIONS2612+Ref: #options2713+Node: General options2855+Ref: #general-options2980+Node: Command options7193+Ref: #command-options7344+Node: Command arguments7744+Ref: #command-arguments7902+Node: Special characters8782+Ref: #special-characters8945+Node: Single escaping shell metacharacters9108+Ref: #single-escaping-shell-metacharacters9349+Node: Double escaping regular expression metacharacters9952+Ref: #double-escaping-regular-expression-metacharacters10263+Node: Triple escaping for add-on commands10789+Ref: #triple-escaping-for-add-on-commands11049+Node: Less escaping11693+Ref: #less-escaping11847+Node: Unicode characters12171+Ref: #unicode-characters12336+Node: Regular expressions13748+Ref: #regular-expressions13888+Node: ENVIRONMENT15624+Ref: #environment15740+Node: DATA FILES17232+Ref: #data-files17351+Node: Data formats17890+Ref: #data-formats18008+Node: Multiple files19402+Ref: #multiple-files19544+Node: Strict mode20013+Ref: #strict-mode20128+Node: TIME PERIODS20852+Ref: #time-periods20969+Node: Smart dates21067+Ref: #smart-dates21193+Node: Report start & end date23023+Ref: #report-start-end-date23198+Node: Report intervals24865+Ref: #report-intervals25033+Node: Period expressions26772+Ref: #period-expressions26912+Node: Period expressions with a report interval28643+Ref: #period-expressions-with-a-report-interval28875+Node: More complex report intervals29956+Ref: #more-complex-report-intervals30205+Node: Intervals with custom start date30840+Ref: #intervals-with-custom-start-date31072+Node: Periods or dates ?32646+Ref: #periods-or-dates32848+Node: Events on multiple weekdays33290+Ref: #events-on-multiple-weekdays33469+Node: DEPTH34332+Ref: #depth34432+Node: QUERIES34766+Ref: #queries34875+Node: Query types35816+Ref: #query-types35935+Node: Combining query terms39109+Ref: #combining-query-terms39284+Node: Queries and command options40087+Ref: #queries-and-command-options40290+Node: Queries and account aliases40539+Ref: #queries-and-account-aliases40742+Node: Queries and valuation40862+Ref: #queries-and-valuation41055+Node: Querying with account aliases41284+Ref: #querying-with-account-aliases41493+Node: Querying with cost or value41623+Ref: #querying-with-cost-or-value41798+Node: CONVERSION & COST42099+Ref: #conversion-cost42232+Node: Recording conversions43121+Ref: #recording-conversions43293+Node: Implicit conversion43745+Ref: #implicit-conversion43902+Node: Priced conversion44721+Ref: #priced-conversion44900+Node: Equity conversion45308+Ref: #equity-conversion45492+Node: Priced equity conversion46280+Ref: #priced-equity-conversion46452+Node: Inferring missing conversion rates46800+Ref: #inferring-missing-conversion-rates47040+Node: Inferring missing equity postings47156+Ref: #inferring-missing-equity-postings47387+Node: Cost reporting47535+Ref: #cost-reporting47712+Node: Conversion summary48232+Ref: #conversion-summary48375+Node: VALUATION49097+Ref: #valuation49215+Node: -V Value49982+Ref: #v-value50106+Node: -X Value in specified commodity50301+Ref: #x-value-in-specified-commodity50494+Node: Valuation date50643+Ref: #valuation-date50805+Node: Market prices51242+Ref: #market-prices51424+Node: --infer-market-prices market prices from transactions52607+Ref: #infer-market-prices-market-prices-from-transactions52874+Node: Valuation commodity54230+Ref: #valuation-commodity54441+Node: Simple valuation examples55667+Ref: #simple-valuation-examples55863+Node: --value Flexible valuation56522+Ref: #value-flexible-valuation56724+Node: More valuation examples58368+Ref: #more-valuation-examples58575+Node: Interaction of valuation and queries60574+Ref: #interaction-of-valuation-and-queries60813+Node: Effect of valuation on reports61285+Ref: #effect-of-valuation-on-reports61480+Node: PIVOTING69177+Ref: #pivoting69282+Node: OUTPUT70958+Ref: #output71060+Node: Output destination71151+Ref: #output-destination71285+Node: Output styling71942+Ref: #output-styling72090+Node: Output format72847+Ref: #output-format72991+Node: CSV output74355+Ref: #csv-output74473+Node: HTML output74576+Ref: #html-output74716+Node: JSON output74810+Ref: #json-output74950+Node: SQL output75867+Ref: #sql-output75985+Node: Commodity styles76486+Ref: #commodity-styles76613+Node: COMMANDS77389+Ref: #commands77501+Node: accounts80866+Ref: #accounts80966+Node: activity81774+Ref: #activity81886+Node: add82269+Ref: #add82372+Node: aregister85165+Ref: #aregister85279+Node: aregister and custom posting dates87644+Ref: #aregister-and-custom-posting-dates87810+Node: balance88362+Ref: #balance88481+Node: balance features89474+Ref: #balance-features89614+Node: Simple balance report91538+Ref: #simple-balance-report91720+Node: Filtered balance report93200+Ref: #filtered-balance-report93387+Node: List or tree mode93714+Ref: #list-or-tree-mode93882+Node: Depth limiting95227+Ref: #depth-limiting95393+Node: Dropping top-level accounts95994+Ref: #dropping-top-level-accounts96196+Node: Multi-period balance report96506+Ref: #multi-period-balance-report96719+Node: Showing declared accounts98994+Ref: #showing-declared-accounts99187+Node: Data layout99718+Ref: #data-layout99873+Node: Sorting by amount107813+Ref: #sorting-by-amount107968+Node: Percentages108638+Ref: #percentages108796+Node: Balance change end balance109757+Ref: #balance-change-end-balance109950+Node: Balance report types111378+Ref: #balance-report-types111568+Node: Useful balance reports115847+Ref: #useful-balance-reports116028+Node: Budget report117113+Ref: #budget-report117297+Node: Budget report start date122572+Ref: #budget-report-start-date122750+Node: Budgets and subaccounts124082+Ref: #budgets-and-subaccounts124289+Node: Selecting budget goals127729+Ref: #selecting-budget-goals127901+Node: Customising single-period balance reports128935+Ref: #customising-single-period-balance-reports129144+Node: balancesheet131319+Ref: #balancesheet131457+Node: balancesheetequity132756+Ref: #balancesheetequity132907+Node: cashflow134287+Ref: #cashflow134411+Node: check135557+Ref: #check135662+Node: Basic checks136296+Ref: #basic-checks136414+Node: Strict checks136965+Ref: #strict-checks137106+Node: Other checks137542+Ref: #other-checks137682+Node: Custom checks138039+Ref: #custom-checks138159+Node: close138576+Ref: #close138680+Node: close and prices140771+Ref: #close-and-prices140900+Node: close date141295+Ref: #close-date141479+Node: Example close asset/liability accounts for file transition142236+Ref: #example-close-assetliability-accounts-for-file-transition142537+Node: Hiding opening/closing transactions143396+Ref: #hiding-openingclosing-transactions143667+Node: close and balance assertions145044+Ref: #close-and-balance-assertions145302+Node: Example close revenue/expense accounts to retained earnings146656+Ref: #example-close-revenueexpense-accounts-to-retained-earnings146934+Node: codes147824+Ref: #codes147934+Node: commodities148646+Ref: #commodities148775+Node: descriptions148857+Ref: #descriptions148987+Node: diff149291+Ref: #diff149399+Node: files150446+Ref: #files150548+Node: help150695+Ref: #help150797+Node: import151615+Ref: #import151731+Node: Deduplication152596+Ref: #deduplication152721+Node: Import testing154615+Ref: #import-testing154780+Node: Importing balance assignments155268+Ref: #importing-balance-assignments155474+Node: Commodity display styles156123+Ref: #commodity-display-styles156296+Node: incomestatement156425+Ref: #incomestatement156560+Node: notes157865+Ref: #notes157980+Node: payees158348+Ref: #payees158456+Node: prices158982+Ref: #prices159090+Node: print159459+Ref: #print159571+Node: print-unique164939+Ref: #print-unique165067+Node: register165352+Ref: #register165481+Node: Custom register output169927+Ref: #custom-register-output170058+Node: register-match171395+Ref: #register-match171531+Node: rewrite171882+Ref: #rewrite171999+Node: Re-write rules in a file173905+Ref: #re-write-rules-in-a-file174068+Node: Diff output format175217+Ref: #diff-output-format175400+Node: rewrite vs print --auto176492+Ref: #rewrite-vs.-print---auto176652+Node: roi177208+Ref: #roi177308+Node: Spaces and special characters in --inv and --pnl179033+Ref: #spaces-and-special-characters-in---inv-and---pnl179273+Node: Semantics of --inv and --pnl179761+Ref: #semantics-of---inv-and---pnl180000+Node: IRR and TWR explained181850+Ref: #irr-and-twr-explained182010+Node: stats185096+Ref: #stats185197+Node: tags186577+Ref: #tags186677+Node: test187196+Ref: #test187312+Node: About add-on commands188059+Ref: #about-add-on-commands188196+Node: JOURNAL FORMAT189327+Ref: #journal-format189455+Node: Transactions191682+Ref: #transactions191797+Node: Dates192811+Ref: #dates192927+Node: Simple dates192992+Ref: #simple-dates193112+Node: Secondary dates193621+Ref: #secondary-dates193769+Node: Posting dates195105+Ref: #posting-dates195228+Node: Status196600+Ref: #status196710+Node: Code198418+Ref: #code198530+Node: Description198762+Ref: #description198890+Node: Payee and note199210+Ref: #payee-and-note199318+Node: Comments199653+Ref: #comments199775+Node: Tags200969+Ref: #tags-1201080+Node: Postings202473+Ref: #postings202597+Node: Virtual postings203623+Ref: #virtual-postings203734+Node: Account names205039+Ref: #account-names205176+Node: Amounts205664+Ref: #amounts205801+Node: Decimal marks digit group marks206786+Ref: #decimal-marks-digit-group-marks206963+Node: Commodity207984+Ref: #commodity208173+Node: Directives influencing number parsing and display209125+Ref: #directives-influencing-number-parsing-and-display209386+Node: Commodity display style209879+Ref: #commodity-display-style210087+Node: Rounding212282+Ref: #rounding212402+Node: Transaction prices212814+Ref: #transaction-prices212980+Node: Lot prices lot dates215411+Ref: #lot-prices-lot-dates215594+Node: Balance assertions216082+Ref: #balance-assertions216260+Node: Assertions and ordering217293+Ref: #assertions-and-ordering217475+Node: Assertions and included files218175+Ref: #assertions-and-included-files218412+Node: Assertions and multiple -f options218745+Ref: #assertions-and-multiple--f-options218995+Node: Assertions and commodities219127+Ref: #assertions-and-commodities219353+Node: Assertions and prices220510+Ref: #assertions-and-prices220718+Node: Assertions and subaccounts221158+Ref: #assertions-and-subaccounts221381+Node: Assertions and virtual postings221705+Ref: #assertions-and-virtual-postings221941+Node: Assertions and precision222083+Ref: #assertions-and-precision222270+Node: Balance assignments222537+Ref: #balance-assignments222707+Node: Balance assignments and prices223871+Ref: #balance-assignments-and-prices224037+Node: Directives224261+Ref: #directives224424+Node: Directives and multiple files228916+Ref: #directives-and-multiple-files229112+Node: Comment blocks229804+Ref: #comment-blocks229981+Node: Including other files230157+Ref: #including-other-files230331+Node: Default year231255+Ref: #default-year231413+Node: Declaring payees231820+Ref: #declaring-payees231991+Node: Declaring the decimal mark232237+Ref: #declaring-the-decimal-mark232437+Node: Declaring commodities232834+Ref: #declaring-commodities233025+Node: Commodity error checking235543+Ref: #commodity-error-checking235693+Node: Default commodity236208+Ref: #default-commodity236388+Node: Declaring market prices237504+Ref: #declaring-market-prices237693+Node: Declaring accounts238506+Ref: #declaring-accounts238686+Node: Account error checking239910+Ref: #account-error-checking240076+Node: Account comments241255+Ref: #account-comments241439+Node: Account subdirectives241880+Ref: #account-subdirectives242065+Node: Account types242383+Ref: #account-types242557+Node: Account display order246231+Ref: #account-display-order246391+Node: Rewriting accounts247542+Ref: #rewriting-accounts247721+Node: Basic aliases248761+Ref: #basic-aliases248897+Node: Regex aliases249641+Ref: #regex-aliases249803+Node: Combining aliases250522+Ref: #combining-aliases250705+Node: Aliases and multiple files251981+Ref: #aliases-and-multiple-files252180+Node: end aliases252759+Ref: #end-aliases252953+Node: Aliases can generate bad account names253102+Ref: #aliases-can-generate-bad-account-names253345+Node: Aliases and account types253930+Ref: #aliases-and-account-types254127+Node: Default parent account254823+Ref: #default-parent-account255013+Node: Periodic transactions255897+Ref: #periodic-transactions256080+Node: Periodic rule syntax257997+Ref: #periodic-rule-syntax258197+Node: Two spaces between period expression and description!258901+Ref: #two-spaces-between-period-expression-and-description259214+Node: Forecasting with periodic transactions259898+Ref: #forecasting-with-periodic-transactions260197+Node: Budgeting with periodic transactions262968+Ref: #budgeting-with-periodic-transactions263201+Node: Auto postings263610+Ref: #auto-postings263746+Node: Auto postings and multiple files265925+Ref: #auto-postings-and-multiple-files266123+Node: Auto postings and dates266332+Ref: #auto-postings-and-dates266600+Node: Auto postings and transaction balancing / inferred amounts / balance assertions266775+Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions267120+Node: Auto posting tags267623+Ref: #auto-posting-tags267832+Node: CSV FORMAT268468+Ref: #csv-format268596+Node: Examples271225+Ref: #examples271328+Node: Basic271536+Ref: #basic271638+Node: Bank of Ireland272180+Ref: #bank-of-ireland272317+Node: Amazon273779+Ref: #amazon273899+Node: Paypal275618+Ref: #paypal275714+Node: CSV rules283358+Ref: #csv-rules283476+Node: skip283809+Ref: #skip283909+Node: fields list284284+Ref: #fields-list284423+Node: field assignment285989+Ref: #field-assignment286141+Node: Field names287176+Ref: #field-names287316+Node: date field287696+Ref: #date-field287816+Node: date2 field287864+Ref: #date2-field288007+Node: status field288063+Ref: #status-field288208+Node: code field288257+Ref: #code-field288404+Node: description field288449+Ref: #description-field288611+Node: comment field288670+Ref: #comment-field288827+Node: account field289138+Ref: #account-field289290+Node: amount field289865+Ref: #amount-field290016+Node: currency field291261+Ref: #currency-field291416+Node: balance field291673+Ref: #balance-field291807+Node: separator292179+Ref: #separator292311+Node: if block292851+Ref: #if-block292978+Node: Matching the whole record293379+Ref: #matching-the-whole-record293556+Node: Matching individual fields294359+Ref: #matching-individual-fields294565+Node: Combining matchers294789+Ref: #combining-matchers294987+Node: Rules applied on successful match295300+Ref: #rules-applied-on-successful-match295493+Node: if table296147+Ref: #if-table296268+Node: end298006+Ref: #end298120+Node: date-format298344+Ref: #date-format298478+Node: decimal-mark299474+Ref: #decimal-mark299621+Node: newest-first299960+Ref: #newest-first300103+Node: include300786+Ref: #include300919+Node: balance-type301363+Ref: #balance-type301485+Node: Tips302185+Ref: #tips302276+Node: Rapid feedback302575+Ref: #rapid-feedback302694+Node: Valid CSV303146+Ref: #valid-csv303278+Node: File Extension303470+Ref: #file-extension303624+Node: Reading multiple CSV files304053+Ref: #reading-multiple-csv-files304240+Node: Valid transactions304481+Ref: #valid-transactions304661+Node: Deduplicating importing305289+Ref: #deduplicating-importing305470+Node: Setting amounts306503+Ref: #setting-amounts306660+Node: Amount signs309104+Ref: #amount-signs309258+Node: Setting currency/commodity309945+Ref: #setting-currencycommodity310133+Node: Amount decimal places311307+Ref: #amount-decimal-places311499+Node: Referencing other fields311811+Ref: #referencing-other-fields312010+Node: How CSV rules are evaluated312907+Ref: #how-csv-rules-are-evaluated313082+Node: TIMECLOCK FORMAT314533+Ref: #timeclock-format314673+Node: TIMEDOT FORMAT316734+Ref: #timedot-format316872+Node: COMMON TASKS321434+Ref: #common-tasks321563+Node: Getting help321970+Ref: #getting-help322104+Node: Constructing command lines322665+Ref: #constructing-command-lines322859+Node: Starting a journal file323556+Ref: #starting-a-journal-file323756+Node: Setting opening balances324944+Ref: #setting-opening-balances325142+Node: Recording transactions328283+Ref: #recording-transactions328465+Node: Reconciling329021+Ref: #reconciling329166+Node: Reporting331423+Ref: #reporting331565+Node: Migrating to a new file335564+Ref: #migrating-to-a-new-file335714+Node: LIMITATIONS336013+Ref: #limitations336141+Node: TROUBLESHOOTING336884+Ref: #troubleshooting336999  End Tag Table