hledger 1.32 → 1.32.1

raw patch · 17 files changed

+41245/−41121 lines, 17 filesdep ~hledger-libdep ~megaparsecPVP: major bump suggested

API removals or changes: PVP suggests a major version bump

Dependency ranges changed: hledger-lib, megaparsec

API changes (from Hackage documentation)

Files

• CHANGES.md +20/−0
• Hledger/Cli/Commands/Import.hs +11/−7
• Hledger/Cli/Commands/Print.hs +33/−36
• Hledger/Cli/Utils.hs +0/−5
• embeddedfiles/hledger-ui.1 +2/−2
• embeddedfiles/hledger-ui.info +41/−41
• embeddedfiles/hledger-ui.txt +2/−2
• embeddedfiles/hledger-web.1 +2/−2
• embeddedfiles/hledger-web.info +25/−25
• embeddedfiles/hledger-web.txt +109/−109
• embeddedfiles/hledger.1 +22/−9
• embeddedfiles/hledger.info +11513/−11485
• embeddedfiles/hledger.txt +8961/−8948
• hledger.1 +22/−9
• hledger.cabal +8/−8
• hledger.info +11513/−11485
• hledger.txt +8961/−8948

@@ -21,6 +21,26 @@ User-visible changes in the hledger command line tool and library.  +# 1.32.1 2023-12-07++- Fixed: `import` with multiple files now updates .latest files correctly. (#2125)++- Fixed: `print --round=hard` now properly pads/rounds amounts with inferred costs. (#2123)++- CSV matcher syntax: mention that ! and & can't be used in the same line yet. (#2088)++- Drop the "a difference of ..." line from balance assertion failure output.+  I feel it made the message harder to read and isn't really necessary.++- Declaring the empty payee name with `payee ""` now works,+  to let `hledger check payees` accept payee-less transactions.+  (#2119)++- Built-in tags with special meaning like `type:` and `t:` are now implicitly declared,+  so using type: in account declarations or generating t: with timedot letters +  won't cause `hledger check tags` to fail.+  (#2119)+ # 1.32 2023-12-01  Breaking changes

@@ -54,10 +54,10 @@   case inputfiles of     [] -> error' "please provide one or more input files as arguments"  -- PARTIAL:     fs -> do-      enewjandlatestdates <- runExceptT $ readJournalFilesAndLatestDates iopts' fs-      case enewjandlatestdates of+      enewjandlatestdatesforfiles <- runExceptT $ readJournalFilesAndLatestDates iopts' fs+      case enewjandlatestdatesforfiles of         Left err -> error' err-        Right (newj, latestdates) ->+        Right (newj, latestdatesforfiles) ->           case sortOn tdate $ jtxns newj of             -- with --dry-run the output should be valid journal format, so messages have ; prepended             [] -> do@@ -71,23 +71,27 @@             newts -> do               if dryrun               then do-                -- first show imported txns+                -- show txns to be imported                 printf "; would import %d new transactions from %s:\n\n" (length newts) inputstr                 mapM_ (T.putStr . showTransaction) newts+                 -- then check the whole journal with them added, if in strict mode                 when (strict_ iopts) $ strictChecks                else do                 -- first check the whole journal with them added, if in strict mode                 when (strict_ iopts) $ strictChecks-                -- then add (append) the transactions to the main journal file++                -- then append the transactions to the main journal file.                 -- XXX This writes unix line endings (\n), some at least,                 -- even if the file uses dos line endings (\r\n), which could leave                 -- mixed line endings in the file. See also writeFileWithBackupIfChanged.                 foldM_ (`journalAddTransaction` opts) j newts  -- gets forced somehow.. (how ?)+                 printf "imported %d new transactions from %s to %s\n" (length newts) inputstr (journalFilePath j)-                -- and finally update the .latest files-                mapM_ (saveLatestDates latestdates . snd . splitReaderPrefix) fs++                -- and if we got this far, update each file's .latest file+                saveLatestDatesForFiles latestdatesforfiles                where                 -- add the new transactions to the journal in memory and check the whole thing

@@ -113,55 +113,52 @@       where styles0 = journalCommodityStyles j      fmt = outputFormatFromOpts opts-    render | fmt=="txt"  = entriesReportAsText opts      . styleAmounts styles-           | fmt=="beancount" = entriesReportAsBeancount opts . styleAmounts styles-           | fmt=="csv"  = printCSV . entriesReportAsCsv . styleAmounts styles-           | fmt=="tsv"  = printTSV . entriesReportAsCsv . styleAmounts styles-           | fmt=="json" = toJsonText                    . styleAmounts styles-           | fmt=="sql"  = entriesReportAsSql            . styleAmounts styles-           | otherwise   = error' $ unsupportedOutputFormatError fmt  -- PARTIAL:--entriesReportAsText :: CliOpts -> EntriesReport -> TL.Text-entriesReportAsText = entriesReportAsTextHelper showTransaction--entriesReportAsTextHelper :: (Transaction -> T.Text) -> CliOpts -> EntriesReport -> TL.Text-entriesReportAsTextHelper showtxn opts =-    TB.toLazyText . foldMap (TB.fromText . showtxn . txntransform)-  where-    txntransform-      -- Use the fully inferred and amount-styled/rounded transaction in the following situations:-      -- with -x/--explicit:-      | boolopt "explicit" (rawopts_ opts) = id-      -- with --show-costs:-      | opts ^. infer_costs = id-      -- with -B/-V/-X/--value ("because of #551, and because of print -V valuing only one posting when there's an implicit txn price.")-      | has (value . _Just) opts = id-      -- Otherwise, keep the transaction's amounts close to how they were written in the journal.-      | otherwise = transactionWithMostlyOriginalPostings+    render | fmt=="txt"       = entriesReportAsText           . styleAmounts styles . map maybeoriginalamounts+           | fmt=="beancount" = entriesReportAsBeancount      . styleAmounts styles . map maybeoriginalamounts+           | fmt=="csv"       = printCSV . entriesReportAsCsv . styleAmounts styles+           | fmt=="tsv"       = printTSV . entriesReportAsCsv . styleAmounts styles+           | fmt=="json"      = toJsonText                    . styleAmounts styles+           | fmt=="sql"       = entriesReportAsSql            . styleAmounts styles+           | otherwise        = error' $ unsupportedOutputFormatError fmt  -- PARTIAL:+      where+        maybeoriginalamounts+          -- Use the fully inferred and amount-styled/rounded transaction in the following situations:+          -- with -x/--explicit:+          | boolopt "explicit" (rawopts_ opts) = id+          -- with --show-costs:+          | opts ^. infer_costs = id+          -- with -B/-V/-X/--value ("because of #551, and because of print -V valuing only one posting when there's an implicit txn price.")+          | has (value . _Just) opts = id+          -- Otherwise, keep the transaction's amounts close to how they were written in the journal.+          | otherwise = transactionWithMostlyOriginalPostings  -- | Replace this transaction's postings with the original postings if any, but keep the -- current possibly rewritten account names, and the inferred values of any auto postings. -- This is mainly for showing transactions with the amounts in their original journal format. transactionWithMostlyOriginalPostings :: Transaction -> Transaction transactionWithMostlyOriginalPostings = transactionMapPostings postingMostlyOriginal---- Get the original posting if any, but keep the current (possibly rewritten) account name,--- and the amounts of any auto postings.-postingMostlyOriginal p = orig-    { paccount = paccount p-    , pamount = pamount $ if isGenerated then p else orig }   where-    orig = originalPosting p-    isGenerated = "_generated-posting" `elem` map fst (ptags p)+    postingMostlyOriginal p = orig+        { paccount = paccount p+        , pamount = pamount $ if isGenerated then p else orig }+      where+        orig = originalPosting p+        isGenerated = "_generated-posting" `elem` map fst (ptags p) +entriesReportAsText :: EntriesReport -> TL.Text+entriesReportAsText = entriesReportAsTextHelper showTransaction++entriesReportAsTextHelper :: (Transaction -> T.Text) -> EntriesReport -> TL.Text+entriesReportAsTextHelper showtxn = TB.toLazyText . foldMap (TB.fromText . showtxn)+ -- In addition to rendering the transactions in (best effort) Beancount format, -- this generates an account open directive for each account name used -- (using the earliest transaction date).-entriesReportAsBeancount :: CliOpts -> EntriesReport -> TL.Text-entriesReportAsBeancount opts ts =+entriesReportAsBeancount :: EntriesReport -> TL.Text+entriesReportAsBeancount ts =   -- PERF: gathers and converts all account names, then repeats that work when showing each transaction   opendirectives <> "\n" <>-  entriesReportAsTextHelper showTransactionBeancount opts ts+  entriesReportAsTextHelper showTransactionBeancount ts   where     opendirectives       | null ts = ""

@@ -20,7 +20,6 @@      openBrowserOn,      writeFileWithBackup,      writeFileWithBackupIfChanged,-     readFileStrictly,      pivotByOpts,      anonymiseByOpts,      journalSimilarTransaction,@@ -29,7 +28,6 @@     ) where -import Control.Exception as C import Control.Monad.Except (ExceptT) import Control.Monad.IO.Class (liftIO) import Data.List@@ -222,9 +220,6 @@ -- overwrite it with this new text, or give an error. writeFileWithBackup :: FilePath -> String -> IO () writeFileWithBackup f t = backUpFile f >> writeFile f t--readFileStrictly :: FilePath -> IO T.Text-readFileStrictly f = readFilePortably f >>= \s -> C.evaluate (T.length s) >> return s  -- | Back up this file with a (incrementing) numbered suffix, or give an error. backUpFile :: FilePath -> IO ()

@@ -1,5 +1,5 @@ -.TH "HLEDGER-UI" "1" "December 2023" "hledger-ui-1.32 " "hledger User Manuals"+.TH "HLEDGER-UI" "1" "December 2023" "hledger-ui-1.32.1 " "hledger User Manuals"   @@ -12,7 +12,7 @@ .PD \f[CR]hledger ui -- [OPTS] [QUERYARGS]\f[R] .SH DESCRIPTION-This manual is for hledger\[aq]s terminal interface, version 1.32.+This manual is for hledger\[aq]s terminal interface, version 1.32.1. See also the hledger manual for common concepts and file formats. .PP hledger is a robust, user-friendly, cross-platform set of programs for

@@ -16,7 +16,7 @@    'hledger-ui [OPTS] [QUERYARGS]' 'hledger ui -- [OPTS] [QUERYARGS]' -   This manual is for hledger's terminal interface, version 1.32.  See+   This manual is for hledger's terminal interface, version 1.32.1.  See also the hledger manual for common concepts and file formats.     hledger is a robust, user-friendly, cross-platform set of programs@@ -674,46 +674,46 @@  Tag Table: Node: Top223-Node: OPTIONS1830-Ref: #options1928-Node: General help options2951-Ref: #general-help-options3100-Node: General input options3382-Ref: #general-input-options3567-Node: General reporting options4269-Ref: #general-reporting-options4433-Node: MOUSE7823-Ref: #mouse7918-Node: KEYS8155-Ref: #keys8248-Node: SCREENS12903-Ref: #screens13001-Node: Menu13581-Ref: #menu13674-Node: Cash accounts13869-Ref: #cash-accounts14011-Node: Balance sheet accounts14195-Ref: #balance-sheet-accounts14376-Node: Income statement accounts14496-Ref: #income-statement-accounts14682-Node: All accounts14846-Ref: #all-accounts14992-Node: Register15174-Ref: #register15298-Node: Transaction17582-Ref: #transaction17705-Node: Error19122-Ref: #error19216-Node: TIPS19460-Ref: #tips19559-Node: Watch mode19601-Ref: #watch-mode19708-Node: Debug output21167-Ref: #debug-output21278-Node: ENVIRONMENT21490-Ref: #environment21600-Node: BUGS21791-Ref: #bugs21874+Node: OPTIONS1832+Ref: #options1930+Node: General help options2953+Ref: #general-help-options3102+Node: General input options3384+Ref: #general-input-options3569+Node: General reporting options4271+Ref: #general-reporting-options4435+Node: MOUSE7825+Ref: #mouse7920+Node: KEYS8157+Ref: #keys8250+Node: SCREENS12905+Ref: #screens13003+Node: Menu13583+Ref: #menu13676+Node: Cash accounts13871+Ref: #cash-accounts14013+Node: Balance sheet accounts14197+Ref: #balance-sheet-accounts14378+Node: Income statement accounts14498+Ref: #income-statement-accounts14684+Node: All accounts14848+Ref: #all-accounts14994+Node: Register15176+Ref: #register15300+Node: Transaction17584+Ref: #transaction17707+Node: Error19124+Ref: #error19218+Node: TIPS19462+Ref: #tips19561+Node: Watch mode19603+Ref: #watch-mode19710+Node: Debug output21169+Ref: #debug-output21280+Node: ENVIRONMENT21492+Ref: #environment21602+Node: BUGS21793+Ref: #bugs21876  End Tag Table 

@@ -9,7 +9,7 @@        hledger ui -- [OPTS] [QUERYARGS]  DESCRIPTION-       This  manual  is  for  hledger's terminal interface, version 1.32.  See+       This  manual  is for hledger's terminal interface, version 1.32.1.  See        also the hledger manual for common concepts and file formats.         hledger is a robust, user-friendly, cross-platform set of programs  for@@ -537,4 +537,4 @@ SEE ALSO        hledger(1), hledger-ui(1), hledger-web(1), ledger(1) -hledger-ui-1.32                  December 2023                   HLEDGER-UI(1)+hledger-ui-1.32.1                December 2023                   HLEDGER-UI(1)

@@ -1,5 +1,5 @@ -.TH "HLEDGER-WEB" "1" "December 2023" "hledger-web-1.32 " "hledger User Manuals"+.TH "HLEDGER-WEB" "1" "December 2023" "hledger-web-1.32.1 " "hledger User Manuals"   @@ -12,7 +12,7 @@ .PD \f[CR]hledger web -- [--serve|--serve-api] [OPTS] [ARGS]\f[R] .SH DESCRIPTION-This manual is for hledger\[aq]s web interface, version 1.32.+This manual is for hledger\[aq]s web interface, version 1.32.1. See also the hledger manual for common concepts and file formats. .PP hledger is a robust, user-friendly, cross-platform set of programs for

@@ -16,7 +16,7 @@    'hledger-web [--serve|--serve-api] [OPTS] [ARGS]' 'hledger web -- [--serve|--serve-api] [OPTS] [ARGS]' -   This manual is for hledger's web interface, version 1.32.  See also+   This manual is for hledger's web interface, version 1.32.1.  See also the hledger manual for common concepts and file formats.     hledger is a robust, user-friendly, cross-platform set of programs@@ -643,30 +643,30 @@  Tag Table: Node: Top225-Node: OPTIONS2577-Ref: #options2682-Node: General help options5970-Ref: #general-help-options6120-Node: General input options6402-Ref: #general-input-options6588-Node: General reporting options7290-Ref: #general-reporting-options7455-Node: PERMISSIONS10845-Ref: #permissions10984-Node: EDITING UPLOADING DOWNLOADING12196-Ref: #editing-uploading-downloading12377-Node: RELOADING13211-Ref: #reloading13345-Node: JSON API13778-Ref: #json-api13893-Node: DEBUG OUTPUT19381-Ref: #debug-output19506-Node: Debug output19533-Ref: #debug-output-119634-Node: ENVIRONMENT20051-Ref: #environment20170-Node: BUGS20287-Ref: #bugs20371+Node: OPTIONS2579+Ref: #options2684+Node: General help options5972+Ref: #general-help-options6122+Node: General input options6404+Ref: #general-input-options6590+Node: General reporting options7292+Ref: #general-reporting-options7457+Node: PERMISSIONS10847+Ref: #permissions10986+Node: EDITING UPLOADING DOWNLOADING12198+Ref: #editing-uploading-downloading12379+Node: RELOADING13213+Ref: #reloading13347+Node: JSON API13780+Ref: #json-api13895+Node: DEBUG OUTPUT19383+Ref: #debug-output19508+Node: Debug output19535+Ref: #debug-output-119636+Node: ENVIRONMENT20053+Ref: #environment20172+Node: BUGS20289+Ref: #bugs20373  End Tag Table 

@@ -9,41 +9,41 @@        hledger web -- [--serve|--serve-api] [OPTS] [ARGS]  DESCRIPTION-       This manual is for hledger's web interface, version 1.32.  See also the-       hledger manual for common concepts and file formats.+       This  manual  is for hledger's web interface, version 1.32.1.  See also+       the hledger manual for common concepts and file formats. -       hledger  is a robust, user-friendly, cross-platform set of programs for-       tracking money, time, or any other commodity,  using  double-entry  ac--       counting  and  a  simple, editable file format.  hledger is inspired by-       and largely compatible with  ledger(1),  and  largely  interconvertible+       hledger is a robust, user-friendly, cross-platform set of programs  for+       tracking  money,  time,  or any other commodity, using double-entry ac-+       counting and a simple, editable file format.  hledger  is  inspired  by+       and  largely  compatible  with  ledger(1), and largely interconvertible        with beancount(1). -       hledger-web  is a simple web application for browsing and adding trans--       actions.  It provides a more user-friendly UI than the hledger  CLI  or-       hledger-ui  TUI,  showing  more  at once (accounts, the current account+       hledger-web is a simple web application for browsing and adding  trans-+       actions.   It  provides a more user-friendly UI than the hledger CLI or+       hledger-ui TUI, showing more at once  (accounts,  the  current  account        register, balance charts) and allowing history-aware data entry, inter-        active searching, and bookmarking. -       hledger-web also lets you share a journal with multiple users, or  even-       the  public  web.   There is no access control, so if you need that you-       should put it behind a suitable  web  proxy.   As  a  small  protection-       against  data  loss  when  running an unprotected instance, it writes a+       hledger-web  also lets you share a journal with multiple users, or even+       the public web.  There is no access control, so if you  need  that  you+       should  put  it  behind  a  suitable  web proxy.  As a small protection+       against data loss when running an unprotected  instance,  it  writes  a        numbered backup of the main journal file (only) on every edit. -       Like hledger, it reads from (and appends to) a journal  file  specified-       by    the    LEDGER_FILE    environment    variable    (defaulting   to-       $HOME/.hledger.journal); or you can specify files with -f options.   It-       can  also  read timeclock files, timedot files, or any CSV/SSV/TSV file+       Like  hledger,  it reads from (and appends to) a journal file specified+       by   the    LEDGER_FILE    environment    variable    (defaulting    to+       $HOME/.hledger.journal);  or you can specify files with -f options.  It+       can also read timeclock files, timedot files, or any  CSV/SSV/TSV  file        with a date field.  (See hledger(1) -> Input for details.)         hledger-web can be run in three modes:         o Transient mode (the default): your default web browser will be opened-         to show the app if possible, and the app  exits  automatically  after-         two  minutes  of inactivity (no requests received and no open browser+         to  show  the  app if possible, and the app exits automatically after+         two minutes of inactivity (no requests received and no  open  browser          windows viewing it). -       o With --serve: the app runs without stopping, and  without  opening  a+       o With  --serve:  the  app runs without stopping, and without opening a          browser.         o With --serve-api: only the JSON API is served.@@ -53,7 +53,7 @@  OPTIONS        Command-line options and arguments may be used to set an initial filter-       on  the data.  These filter options are not shown in the web UI, but it+       on the data.  These filter options are not shown in the web UI, but  it        will be applied in addition to any search query entered there.         hledger-web provides the following options:@@ -62,7 +62,7 @@               serve and log requests, don't browse or auto-exit after timeout         --serve-api-              like --serve, but serve only  the  JSON  web  API,  without  the+              like  --serve,  but  serve  only  the  JSON web API, without the               server-side web UI         --host=IPADDR@@ -72,58 +72,58 @@               listen on this TCP port (default: 5000)         --socket=SOCKETFILE-              use  a unix domain socket file to listen for requests instead of-              a TCP socket.  Implies --serve.  It can only be used if the  op-+              use a unix domain socket file to listen for requests instead  of+              a  TCP socket.  Implies --serve.  It can only be used if the op-               erating system can provide this type of socket.         --base-url=URL-              set  the  base url (default: http://IPADDR:PORT).  Note: affects-              url generation but not route parsing.  Can be useful if  running+              set the base url (default: http://IPADDR:PORT).   Note:  affects+              url  generation but not route parsing.  Can be useful if running               behind a reverse web proxy that does path rewriting.         --file-url=URL               set the static files url (default: BASEURL/static).  hledger-web-              normally  serves static files itself, but if you wanted to serve-              them from another server for efficiency, you would set  the  url+              normally serves static files itself, but if you wanted to  serve+              them  from  another server for efficiency, you would set the url               with this.         --allow=view|add|edit-              set  the  user's  access level for changing data (default: add).-              It also accepts sandstorm for use on that platform  (reads  per-+              set the user's access level for changing  data  (default:  add).+              It  also  accepts sandstorm for use on that platform (reads per-               missions from the X-Sandstorm-Permissions request header). -       --test run  hledger-web's  tests  and exit.  hspec test runner args may+       --test run hledger-web's tests and exit.  hspec test  runner  args  may               follow a --, eg: hledger-web --test -- --help -       By default the server listens on IP address 127.0.0.1, accessible  only-       to  local  requests.   You  can  use  --host  to change this, eg --host+       By  default the server listens on IP address 127.0.0.1, accessible only+       to local requests.  You can  use  --host  to  change  this,  eg  --host        0.0.0.0 to listen on all configured addresses. -       Similarly, use --port to set a TCP port other than 5000, eg if you  are+       Similarly,  use --port to set a TCP port other than 5000, eg if you are        running multiple hledger-web instances.         Both of these options are ignored when --socket is used.  In this case,-       it  creates  an  AF_UNIX socket file at the supplied path and uses that-       for communication.  This is an  alternative  way  of  running  multiple-       hledger-web  instances  behind a reverse proxy that handles authentica--       tion for different users.  The path can be  derived  in  a  predictable+       it creates an AF_UNIX socket file at the supplied path  and  uses  that+       for  communication.   This  is  an  alternative way of running multiple+       hledger-web instances behind a reverse proxy that  handles  authentica-+       tion  for  different  users.   The path can be derived in a predictable        way, eg by using the username within the path.  As an example, nginx as-       reverse  proxy  can use the variable $remote_user to derive a path from-       the username used  in  a  HTTP  basic  authentication.   The  following-       proxy_pass  directive  allows  access to all hledger-web instances that+       reverse proxy can use the variable $remote_user to derive a  path  from+       the  username  used  in  a  HTTP  basic  authentication.  The following+       proxy_pass directive allows access to all  hledger-web  instances  that        created a socket in /tmp/hledger/:                  proxy_pass http://unix:/tmp/hledger/${remote_user}.socket; -       You can use --base-url to change the protocol, hostname, port and  path+       You  can use --base-url to change the protocol, hostname, port and path        that appear in hyperlinks, useful eg for integrating hledger-web within-       a  larger website.  The default is http://HOST:PORT/ using the server's+       a larger website.  The default is http://HOST:PORT/ using the  server's        configured host address and TCP port (or http://HOST if PORT is 80). -       With --file-url you can set a different base url for static  files,  eg+       With  --file-url  you can set a different base url for static files, eg        for better caching or cookie-less serving on high performance websites. -       hledger-web  also  supports  many of hledger's general options (and the+       hledger-web also supports many of hledger's general  options  (and  the        hledger manual's command line tips also apply here):     General help options@@ -146,7 +146,7 @@               $LEDGER_FILE or $HOME/.hledger.journal)         --rules-file=RULESFILE-              Conversion   rules  file  to  use  when  reading  CSV  (default:+              Conversion  rules  file  to  use  when  reading  CSV   (default:               FILE.rules)         --separator=CHAR@@ -165,7 +165,7 @@               assignments)         -s --strict-              do extra error checking (check that all posted accounts are  de-+              do  extra error checking (check that all posted accounts are de-               clared)     General reporting options@@ -193,7 +193,7 @@               multiperiod/multicolumn report by year         -p --period=PERIODEXP-              set  start date, end date, and/or reporting interval all at once+              set start date, end date, and/or reporting interval all at  once               using period expressions syntax         --date2@@ -201,7 +201,7 @@               fects)         --today=DATE-              override  today's  date  (affects  relative  smart  dates,   for+              override   today's  date  (affects  relative  smart  dates,  for               tests/examples)         -U --unmarked@@ -220,21 +220,21 @@               hide/aggregate accounts or postings more than NUM levels deep         -E --empty-              show  items with zero amount, normally hidden (and vice-versa in+              show items with zero amount, normally hidden (and vice-versa  in               hledger-ui/hledger-web)         -B --cost               convert amounts to their cost/selling amount at transaction time         -V --market-              convert amounts to their market value in default valuation  com-+              convert  amounts to their market value in default valuation com-               modities         -X --exchange=COMM               convert amounts to their market value in commodity COMM         --value-              convert  amounts  to  cost  or  market value, more flexibly than+              convert amounts to cost or  market  value,  more  flexibly  than               -B/-V/-X         --infer-equity@@ -244,38 +244,38 @@               infer costs from conversion equity postings         --infer-market-prices-              use costs as additional market prices, as if they were P  direc-+              use  costs as additional market prices, as if they were P direc-               tives         --forecast-              generate  transactions  from  periodic rules, between the latest-              recorded txn and 6 months from today, or  during  the  specified-              PERIOD  (=  is required).  Auto posting rules will be applied to-              these transactions as well.  Also, in  hledger-ui  make  future-+              generate transactions from periodic rules,  between  the  latest+              recorded  txn  and  6 months from today, or during the specified+              PERIOD (= is required).  Auto posting rules will be  applied  to+              these  transactions  as  well.  Also, in hledger-ui make future-               dated transactions visible. -       --auto generate  extra  postings  by applying auto posting rules to all+       --auto generate extra postings by applying auto posting  rules  to  all               txns (not just forecast txns)         --verbose-tags-              add visible tags indicating transactions or postings which  have+              add  visible tags indicating transactions or postings which have               been generated/modified         --commodity-style-              Override  the  commodity  style  in the output for the specified+              Override the commodity style in the  output  for  the  specified               commodity.  For example 'EUR1.000,00'.         --color=WHEN (or --colour=WHEN)-              Should color-supporting commands use ANSI color  codes  in  text-              output.   'auto' (default): whenever stdout seems to be a color--              supporting terminal.  'always' or 'yes': always, useful eg  when-              piping  output  into  'less  -R'.   'never'  or  'no': never.  A+              Should  color-supporting  commands  use ANSI color codes in text+              output.  'auto' (default): whenever stdout seems to be a  color-+              supporting  terminal.  'always' or 'yes': always, useful eg when+              piping output into  'less  -R'.   'never'  or  'no':  never.   A               NO_COLOR environment variable overrides this.         --pretty[=WHEN]-              Show prettier output, e.g.  using  unicode  box-drawing  charac--              ters.   Accepts 'yes' (the default) or 'no' ('y', 'n', 'always',-              'never' also work).  If you provide an  argument  you  must  use+              Show  prettier  output,  e.g.  using unicode box-drawing charac-+              ters.  Accepts 'yes' (the default) or 'no' ('y', 'n',  'always',+              'never'  also  work).   If  you provide an argument you must use               '=', e.g.  '--pretty=yes'.         When a reporting option appears more than once in the command line, the@@ -284,13 +284,13 @@        Some reporting options can also be written as query arguments.  PERMISSIONS-       By  default,  hledger-web  allows  anyone  who can reach it to view the+       By default, hledger-web allows anyone who can  reach  it  to  view  the        journal and to add new transactions, but not to change existing data.         You can restrict who can reach it by -       o setting the IP address it listens on (see --host above).  By  default-         it  listens  on  127.0.0.1,  accessible to all users on the local ma-+       o setting  the IP address it listens on (see --host above).  By default+         it listens on 127.0.0.1, accessible to all users  on  the  local  ma-          chine.         o putting it behind an authenticating proxy, using eg apache or nginx@@ -300,44 +300,44 @@        You can restrict what the users who reach it can do, by         o using the --capabilities=CAP[,CAP..] flag when you start it, enabling-         one or more of the following  capabilities.   The  default  value  is+         one  or  more  of  the  following capabilities.  The default value is          view,add:           o view - allows viewing the journal file and all included files           o add - allows adding new transactions to the main journal file -         o manage  -  allows editing, uploading or downloading the main or in-+         o manage - allows editing, uploading or downloading the main  or  in-            cluded files -       o using the --capabilities-header=HTTPHEADER flag  to  specify  a  HTTP-         header  from  which it will read capabilities to enable.  hledger-web-         on Sandstorm uses the  X-Sandstorm-Permissions  header  to  integrate+       o using  the  --capabilities-header=HTTPHEADER  flag  to specify a HTTP+         header from which it will read capabilities to  enable.   hledger-web+         on  Sandstorm  uses  the  X-Sandstorm-Permissions header to integrate          with Sandstorm's permissions.  This is disabled by default.  EDITING, UPLOADING, DOWNLOADING-       If  you  enable the manage capability mentioned above, you'll see a new-       "spanner" button to the right of the search form.  Clicking  this  will-       let  you edit, upload, or download the journal file or any files it in-+       If you enable the manage capability mentioned above, you'll see  a  new+       "spanner"  button  to the right of the search form.  Clicking this will+       let you edit, upload, or download the journal file or any files it  in-        cludes. -       Note, unlike any other hledger command, in this mode you (or any  visi-+       Note,  unlike any other hledger command, in this mode you (or any visi-        tor) can alter or wipe the data files. -       Normally  whenever  a  file is changed in this way, hledger-web saves a-       numbered backup (assuming file permissions allow it, the  disk  is  not-       full,  etc.)  hledger-web is not aware of version control systems, cur--       rently; if you use one, you'll have to arrange to  commit  the  changes+       Normally whenever a file is changed in this way,  hledger-web  saves  a+       numbered  backup  (assuming  file permissions allow it, the disk is not+       full, etc.)  hledger-web is not aware of version control systems,  cur-+       rently;  if  you  use one, you'll have to arrange to commit the changes        yourself (eg with a cron job or a file watcher like entr). -       Changes  which would leave the journal file(s) unparseable or non-valid-       (eg with failing balance assertions) are prevented.   (Probably.   This+       Changes which would leave the journal file(s) unparseable or  non-valid+       (eg  with  failing balance assertions) are prevented.  (Probably.  This        needs re-testing.)  RELOADING        hledger-web detects changes made to the files by other means (eg if you-       edit  it  directly,  outside  of hledger-web), and it will show the new-       data when you reload the page or navigate to a new page.  If  a  change+       edit it directly, outside of hledger-web), and it  will  show  the  new+       data  when  you reload the page or navigate to a new page.  If a change        makes a file unparseable, hledger-web will display an error message un-        til the file has been fixed. @@ -345,8 +345,8 @@        that both machine clocks are roughly in step.)  JSON API-       In  addition to the web UI, hledger-web also serves a JSON API that can-       be used to get data or add new transactions.  If you want the JSON  API+       In addition to the web UI, hledger-web also serves a JSON API that  can+       be  used to get data or add new transactions.  If you want the JSON API        only, you can use the --serve-api flag.  Eg:                $ hledger-web -f examples/sample.journal --serve-api@@ -363,7 +363,7 @@               /accounttransactions/ACCOUNTNAME         Eg, all account names in the journal (similar to the accounts command).-       (hledger-web's  JSON  does  not include newlines, here we use python to+       (hledger-web's JSON does not include newlines, here we  use  python  to        prettify it):                $ curl -s http://127.0.0.1:5000/accountnames | python -m json.tool@@ -404,25 +404,25 @@                                       "aprice": null,               ... -       Most of the JSON corresponds to hledger's data types;  for  details  of-       what  the fields mean, see the Hledger.Data.Json haddock docs and click-       on the various data types, eg Transaction.  And for a higher level  un-+       Most  of  the  JSON corresponds to hledger's data types; for details of+       what the fields mean, see the Hledger.Data.Json haddock docs and  click+       on  the various data types, eg Transaction.  And for a higher level un-        derstanding, see the journal docs.         In some cases there is outer JSON corresponding to a "Report" type.  To-       understand  that,  go to the Hledger.Web.Handler.MiscR haddock and look-       at the source for the appropriate handler to see what it  returns.   Eg+       understand that, go to the Hledger.Web.Handler.MiscR haddock  and  look+       at  the  source for the appropriate handler to see what it returns.  Eg        for /accounttransactions it's getAccounttransactionsR, returning a "ac--       countTransactionsReport  ...".   Looking up the haddock for that we can-       see that  /accounttransactions  returns  an  AccountTransactionsReport,-       which  consists  of a report title and a list of AccountTransactionsRe-+       countTransactionsReport ...".  Looking up the haddock for that  we  can+       see  that  /accounttransactions  returns  an AccountTransactionsReport,+       which consists of a report title and a list  of  AccountTransactionsRe-        portItem (etc). -       You can add a new transaction to the journal  with  a  PUT  request  to-       /add,  if  hledger-web  was started with the add capability (enabled by+       You  can  add  a  new  transaction to the journal with a PUT request to+       /add, if hledger-web was started with the add  capability  (enabled  by        default).  The payload must be the full, exact JSON representation of a-       hledger transaction (partial data won't do).  You can get  sample  JSON-       from  hledger-web's  /transactions  or /accounttransactions, or you can+       hledger  transaction  (partial data won't do).  You can get sample JSON+       from hledger-web's /transactions or /accounttransactions,  or  you  can        export it with hledger-lib, eg like so:                .../hledger$ stack ghci hledger-lib@@ -518,28 +518,28 @@                   "tstatus": "Unmarked"               } -       And here's how to test adding it with curl.  This should add a new  en-+       And  here's how to test adding it with curl.  This should add a new en-        try to your journal:                $ curl http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.json  DEBUG OUTPUT    Debug output-       You  can  add  --debug[=N]  to the command line to log debug output.  N+       You can add --debug[=N] to the command line to  log  debug  output.   N        ranges from 1 (least output, the default) to 9 (maximum output).  Typi--       cally you would start with 1 and increase until you are seeing  enough.-       Debug  output  goes  to stderr, interleaved with the requests logged on+       cally  you would start with 1 and increase until you are seeing enough.+       Debug output goes to stderr, interleaved with the  requests  logged  on        stdout.  To capture debug output in a log file instead, you can usually        redirect stderr, eg:        hledger-web --debug=3 2>hledger-web.log.  ENVIRONMENT-       LEDGER_FILE The main journal  file  to  use  when  not  specified  with+       LEDGER_FILE  The  main  journal  file  to  use  when not specified with        -f/--file.  Default: $HOME/.hledger.journal.  BUGS        We  welcome  bug  reports  in  the  hledger  issue  tracker  (shortcut:-       http://bugs.hledger.org), or on the #hledger chat or hledger mail  list+       http://bugs.hledger.org),  or on the #hledger chat or hledger mail list        (https://hledger.org/support).         Some known issues:@@ -564,4 +564,4 @@ SEE ALSO        hledger(1), hledger-ui(1), hledger-web(1), ledger(1) -hledger-web-1.32                 December 2023                  HLEDGER-WEB(1)+hledger-web-1.32.1               December 2023                  HLEDGER-WEB(1)

@@ -1,6 +1,6 @@ .\"t -.TH "HLEDGER" "1" "December 2023" "hledger-1.32 " "hledger User Manuals"+.TH "HLEDGER" "1" "December 2023" "hledger-1.32.1 " "hledger User Manuals"   @@ -23,7 +23,7 @@ hledger is inspired by and largely compatible with ledger(1), and largely interconvertible with beancount(1). .PP-This manual is for hledger\[aq]s command line interface, version 1.32.+This manual is for hledger\[aq]s command line interface, version 1.32.1. It also describes the common options, file formats and concepts used by all hledger programs. It might accidentally teach you some bookkeeping/accounting as well!@@ -2796,6 +2796,8 @@ commodity 1 000 000.0000   ; the no-symbol commodity .EE .PP+Commodities do not have tags (tags in the comment will be ignored).+.PP A commodity directive\[aq]s sample amount must always include a period or comma decimal mark (this rule helps disambiguate decimal marks and digit group marks).@@ -2931,10 +2933,18 @@ Eg: .IP .EX-payee Whole Foods+payee Whole Foods    ; a comment .EE .PP-Any indented subdirectives are currently ignored.+Payees do not have tags (tags in the comment will be ignored).+.PP+To declare the empty payee name, use \f[CR]\[dq]\[dq]\f[R].+.IP+.EX+payee \[dq]\[dq]+.EE+.PP+Ledger-style indented subdirectives, if any, are currently ignored. .SS \f[CR]tag\f[R] directive \f[CR]tag TAGNAME\f[R] .PP@@ -4153,7 +4163,7 @@ else. If you have trouble, see \[dq]Regular expressions\[dq] in the hledger manual (https://hledger.org/hledger.html#regular-expressions).-.PP+.SS What matchers match With record matchers, it\[aq]s important to know that the record matched is not the original CSV record, but a modified one: separators will be converted to commas, and enclosing double quotes (but not enclosing@@ -4169,16 +4179,19 @@ .EX 2023-01-01,Acme, Inc.,  1,000 .EE-.PP+.SS Combining matchers When an if block has multiple matchers, they are combined as follows: .IP \[bu] 2 By default they are OR\[aq]d (any one of them can match) .IP \[bu] 2 When a matcher is preceded by ampersand (\f[CR]&\f[R]) it will be-AND\[aq]ed with the previous matcher (both of them must match).+AND\[aq]ed with the previous matcher (both of them must match)+.IP \[bu] 2+When a matcher is preceded by an exclamation mark (\f[CR]!\f[R]), the+matcher is negated (it may not match). .PP-When a matcher is preceded by an exclamation mark (!), the matcher will-be negated, ie it will exclude CSV records that match.+Currently there is a limitation: you can\[aq]t use both \f[CR]&\f[R] and+\f[CR]!\f[R] on the same line (you can\[aq]t AND a negated matcher). .SS Match groups Matchers can define match groups: parenthesised portions of the regular expression which are available for reference in field assignments.

@@ -23,11491 +23,11519 @@ and largely compatible with ledger(1), and largely interconvertible with beancount(1). -   This manual is for hledger's command line interface, version 1.32.-It also describes the common options, file formats and concepts used by-all hledger programs.  It might accidentally teach you some-bookkeeping/accounting as well!  You don't need to know everything in-here to use hledger productively, but when you have a question about-functionality, this doc should answer it.  It is detailed, so do skip-ahead or skim when needed.  You can read it on hledger.org, or as an-info manual or man page on your system.  You can also get it from-hledger itself with-'hledger --man', 'hledger --info' or 'hledger help [TOPIC]'.--   The main function of the hledger CLI is to read plain text files-describing financial transactions, crunch the numbers, and print a-useful report on the terminal (or save it as HTML, CSV, JSON or SQL).-Many reports are available, as subcommands.  hledger will also detect-other 'hledger-*' executables as extra subcommands.--   hledger usually reads from (and appends to) a journal file specified-by the 'LEDGER_FILE' environment variable (defaulting to-'$HOME/.hledger.journal'); or you can specify files with '-f' options.-It can also read timeclock files, timedot files, or any CSV/SSV/TSV file-with a date field.--   Here is a small journal file describing one transaction:--2015-10-16 bought food-  expenses:food          $10-  assets:cash--   Transactions are dated movements of money (etc.)  between two or more-_accounts_: bank accounts, your wallet, revenue/expense categories,-people, etc.  You can choose any account names you wish, using ':' to-indicate subaccounts.  There must be at least two spaces between account-name and amount.  Positive amounts are inflow to that account (_debit_),-negatives are outflow from it (_credit_).  (Some reports show revenue,-liability and equity account balances as negative numbers as a result;-this is normal.)--   hledger's add command can help you add transactions, or you can-install other data entry UIs like hledger-web or hledger-iadd.  For more-extensive/efficient changes, use a text editor: Emacs + ledger-mode, VIM-+ vim-ledger, or VS Code + hledger-vscode are some good choices (see-https://hledger.org/editors.html).--   To get started, run 'hledger add' and follow the prompts, or save-some entries like the above in '$HOME/.hledger.journal', then try-commands like:-'hledger print -x'-'hledger aregister assets'-'hledger balance'-'hledger balancesheet'-'hledger incomestatement'.-Run 'hledger' to list the commands.  See also the "Starting a journal-file" and "Setting opening balances" sections in PART 5: COMMON TASKS.--* Menu:--* PART 1 USER INTERFACE::-* Input::-* Commands::-* Options::-* Command line tips::-* Output::-* Environment::-* PART 2 DATA FORMATS::-* Journal::-* CSV::-* Timeclock::-* Timedot::-* PART 3 REPORTING CONCEPTS::-* Amount formatting parseability::-* Time periods::-* Depth::-* Queries::-* Pivoting::-* Generating data::-* Forecasting::-* Budgeting::-* Cost reporting::-* Value reporting::-* PART 4 COMMANDS::-* PART 5 COMMON TASKS::-* BUGS::---File: hledger.info,  Node: PART 1 USER INTERFACE,  Next: Input,  Prev: Top,  Up: Top--1 PART 1: USER INTERFACE-************************---File: hledger.info,  Node: Input,  Next: Commands,  Prev: PART 1 USER INTERFACE,  Up: Top--2 Input-*******--hledger reads one or more data files, each time you run it.  You can-specify a file with '-f', like so--$ hledger -f FILE print--   Files are most often in hledger's journal format, with the '.journal'-file extension ('.hledger' or '.j' also work); these files describe-transactions, like an accounting general journal.--   When no file is specified, hledger looks for '.hledger.journal' in-your home directory.--   But most people prefer to keep financial files in a dedicated folder,-perhaps with version control.  Also, starting a new journal file each-year is common (it's not required, but helps keep things fast and-organised).  So we usually configure a different journal file, by-setting the 'LEDGER_FILE' environment variable, to something like-'~/finance/2023.journal'.  For more about how to do that on your system,-see Common tasks > Setting LEDGER_FILE.--* Menu:--* Data formats::-* Standard input::-* Multiple files::-* Strict mode::---File: hledger.info,  Node: Data formats,  Next: Standard input,  Up: Input--2.1 Data formats-================--Usually the data file is in hledger's journal format, but it can be in-any of the supported file formats, which currently are:--Reader:       Reads:                          Used for file extensions:------------------------------------------------------------------------------'journal'     hledger journal files and       '.journal' '.j' '.hledger'-              some Ledger journals, for       '.ledger'-              transactions-'timeclock'   timeclock files, for precise    '.timeclock'-              time logging-'timedot'     timedot files, for              '.timedot'-              approximate time logging-'csv'         CSV/SSV/TSV/character-separated '.csv' '.ssv' '.tsv'-              values, for data import         '.csv.rules' '.ssv.rules'-                                              '.tsv.rules'--   These formats are described in more detail below.--   hledger detects the format automatically based on the file extensions-shown above.  If it can't recognise the file extension, it assumes-'journal' format.  So for non-journal files, it's important to use a-recognised file extension, so as to either read successfully or to show-relevant error messages.--   You can also force a specific reader/format by prefixing the file-path with the format and a colon.  Eg, to read a .dat file as csv-format:--$ hledger -f csv:/some/csv-file.dat stats---File: hledger.info,  Node: Standard input,  Next: Multiple files,  Prev: Data formats,  Up: Input--2.2 Standard input-==================--The file name '-' means standard input:--$ cat FILE | hledger -f- print--   If reading non-journal data in this way, you'll need to add a file-format prefix, like:--$ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:----File: hledger.info,  Node: Multiple files,  Next: Strict mode,  Prev: Standard input,  Up: Input--2.3 Multiple files-==================--You can specify multiple '-f' options, to read multiple files as one big-journal.  When doing this, note that certain features (described below)-will be affected:--   * Balance assertions will not see the effect of transactions in-     previous files.  (Usually this doesn't matter as each file will set-     the corresponding opening balances.)-   * Some directives will not affect previous or subsequent files.--   If needed, you can work around these by using a single parent file-which includes the others, or concatenating the files into one, eg: 'cat-a.journal b.journal | hledger -f- CMD'.---File: hledger.info,  Node: Strict mode,  Prev: Multiple files,  Up: Input--2.4 Strict mode-===============--hledger checks input files for valid data.  By default, the most-important errors are detected, while still accepting easy journal files-without a lot of declarations:--   * Are the input files parseable, with valid syntax ?-   * Are all transactions balanced ?-   * Do all balance assertions pass ?--   With the '-s'/'--strict' flag, additional checks are performed:--   * Are all accounts posted to, declared with an 'account' directive ?-     (Account error checking)-   * Are all commodities declared with a 'commodity' directive ?-     (Commodity error checking)-   * Are all commodity conversions declared explicitly ?--   You can use the check command to run individual checks - the ones-listed above and some more.---File: hledger.info,  Node: Commands,  Next: Options,  Prev: Input,  Up: Top--3 Commands-**********--hledger provides various subcommands for getting things done.  Most of-these commands do not change the journal file; they just read it and-output a report.  A few commands assist with adding data and file-management.--   To show the commands list, run 'hledger' with no arguments.  The-commands are described in detail in PART 4: COMMANDS, below.--   To use a particular command, run 'hledger CMD [CMDOPTS] [CMDARGS]',--   * CMD is the full command name, or its standard abbreviation shown in-     the commands list, or any unambiguous prefix of the name.--   * CMDOPTS are command-specific options, if any.  Command-specific-     options must be written after the command name.  Eg: 'hledger print-     -x'.--   * CMDARGS are additional arguments to the command, if any.  Most-     hledger commands accept arguments representing a query, to limit-     the data in some way.  Eg: 'hledger reg assets:checking'.--   To list a command's options, arguments, and documentation in the-terminal, run 'hledger CMD -h'.  Eg: 'hledger bal -h'.--* Menu:--* Add-on commands::---File: hledger.info,  Node: Add-on commands,  Up: Commands--3.1 Add-on commands-===================--In addition to the built-in commands, you can install _add-on commands_:-programs or scripts named "hledger-SOMETHING", which will also appear in-hledger's commands list.  If you used the hledger-install script, you-will have several add-ons installed already.  Some more can be found in-hledger's bin/ directory, documented at-https://hledger.org/scripts.html.--   More precisely, add-on commands are programs or scripts in your-shell's PATH, whose name starts with "hledger-" and ends with no-extension or a recognised extension (".bat", ".com", ".exe", ".hs",-".js", ".lhs", ".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"),-and (on unix and mac) which has executable permission for the current-user.--   You can run add-on commands using hledger, much like built-in-commands: 'hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]'.  But note-the double hyphen argument, required before add-on-specific options.-Eg: 'hledger ui -- --watch' or 'hledger web -- --serve'.  If this causes-difficulty, you can always run the add-on directly, without using-'hledger': 'hledger-ui --watch' or 'hledger-web --serve'.---File: hledger.info,  Node: Options,  Next: Command line tips,  Prev: Commands,  Up: Top--4 Options-*********--Run 'hledger -h' to see general command line help, and general options-which are common to most hledger commands.  These options can be written-anywhere on the command line.  They can be grouped into help, input, and-reporting options:--* Menu:--* General help options::-* General input options::-* General reporting options::---File: hledger.info,  Node: General help options,  Next: General input options,  Up: Options--4.1 General help options-========================--'-h --help'--     show general or COMMAND help-'--man'--     show general or COMMAND user manual with man-'--info'--     show general or COMMAND user manual with info-'--version'--     show general or ADDONCMD version-'--debug[=N]'--     show debug output (levels 1-9, default: 1)---File: hledger.info,  Node: General input options,  Next: General reporting options,  Prev: General help options,  Up: Options--4.2 General input options-=========================--'-f FILE --file=FILE'--     use a different input file.  For stdin, use - (default:-     '$LEDGER_FILE' or '$HOME/.hledger.journal')-'--rules-file=RULESFILE'--     Conversion rules file to use when reading CSV (default: FILE.rules)-'--separator=CHAR'--     Field separator to expect when reading CSV (default: ',')-'--alias=OLD=NEW'--     rename accounts named OLD to NEW-'--anon'--     anonymize accounts and payees-'--pivot FIELDNAME'--     use some other field or tag for the account name-'-I --ignore-assertions'--     disable balance assertion checks (note: does not disable balance-     assignments)-'-s --strict'--     do extra error checking (check that all posted accounts are-     declared)---File: hledger.info,  Node: General reporting options,  Prev: General input options,  Up: Options--4.3 General reporting options-=============================--'-b --begin=DATE'--     include postings/txns on or after this date (will be adjusted to-     preceding subperiod start when using a report interval)-'-e --end=DATE'--     include postings/txns before this date (will be adjusted to-     following subperiod end when using a report interval)-'-D --daily'--     multiperiod/multicolumn report by day-'-W --weekly'--     multiperiod/multicolumn report by week-'-M --monthly'--     multiperiod/multicolumn report by month-'-Q --quarterly'--     multiperiod/multicolumn report by quarter-'-Y --yearly'--     multiperiod/multicolumn report by year-'-p --period=PERIODEXP'--     set start date, end date, and/or reporting interval all at once-     using period expressions syntax-'--date2'--     match the secondary date instead (see command help for other-     effects)-'--today=DATE'--     override today's date (affects relative smart dates, for-     tests/examples)-'-U --unmarked'--     include only unmarked postings/txns (can combine with -P or -C)-'-P --pending'--     include only pending postings/txns-'-C --cleared'--     include only cleared postings/txns-'-R --real'--     include only non-virtual postings-'-NUM --depth=NUM'--     hide/aggregate accounts or postings more than NUM levels deep-'-E --empty'--     show items with zero amount, normally hidden (and vice-versa in-     hledger-ui/hledger-web)-'-B --cost'--     convert amounts to their cost/selling amount at transaction time-'-V --market'--     convert amounts to their market value in default valuation-     commodities-'-X --exchange=COMM'--     convert amounts to their market value in commodity COMM-'--value'--     convert amounts to cost or market value, more flexibly than-     -B/-V/-X-'--infer-equity'--     infer conversion equity postings from costs-'--infer-costs'--     infer costs from conversion equity postings-'--infer-market-prices'--     use costs as additional market prices, as if they were P directives-'--forecast'--     generate transactions from periodic rules, between the latest-     recorded txn and 6 months from today, or during the specified-     PERIOD (= is required).  Auto posting rules will be applied to-     these transactions as well.  Also, in hledger-ui make future-dated-     transactions visible.-'--auto'--     generate extra postings by applying auto posting rules to all txns-     (not just forecast txns)-'--verbose-tags'--     add visible tags indicating transactions or postings which have-     been generated/modified-'--commodity-style'--     Override the commodity style in the output for the specified-     commodity.  For example 'EUR1.000,00'.-'--color=WHEN (or --colour=WHEN)'--     Should color-supporting commands use ANSI color codes in text-     output.  'auto' (default): whenever stdout seems to be a-     color-supporting terminal.  'always' or 'yes': always, useful eg-     when piping output into 'less -R'. 'never' or 'no': never.  A-     NO_COLOR environment variable overrides this.-'--pretty[=WHEN]'--     Show prettier output, e.g.  using unicode box-drawing characters.-     Accepts 'yes' (the default) or 'no' ('y', 'n', 'always', 'never'-     also work).  If you provide an argument you must use '=', e.g.-     '-pretty=yes'.--   When a reporting option appears more than once in the command line,-the last one takes precedence.--   Some reporting options can also be written as query arguments.---File: hledger.info,  Node: Command line tips,  Next: Output,  Prev: Options,  Up: Top--5 Command line tips-*******************--Here are some details useful to know about for hledger command lines-(and elsewhere).  Feel free to skip this section until you need it.--* Menu:--* Option repetition::-* Special characters::-* Unicode characters::-* Regular expressions::-* Argument files::---File: hledger.info,  Node: Option repetition,  Next: Special characters,  Up: Command line tips--5.1 Option repetition-=====================--If options are repeated in a command line, hledger will generally use-the last (right-most) occurence.---File: hledger.info,  Node: Special characters,  Next: Unicode characters,  Prev: Option repetition,  Up: Command line tips--5.2 Special characters-======================--* Menu:--* Single escaping shell metacharacters::-* Double escaping regular expression metacharacters::-* Triple escaping for add-on commands::-* Less escaping::---File: hledger.info,  Node: Single escaping shell metacharacters,  Next: Double escaping regular expression metacharacters,  Up: Special characters--5.2.1 Single escaping (shell metacharacters)-----------------------------------------------In shell command lines, characters significant to your shell - such as-spaces, '<', '>', '(', ')', '|', '$' and '\' - should be "shell-escaped"-if you want hledger to see them.  This is done by enclosing them in-single or double quotes, or by writing a backslash before them.  Eg to-match an account name containing a space:--$ hledger register 'credit card'--   or:--$ hledger register credit\ card--   Windows users should keep in mind that 'cmd' treats single quote as a-regular character, so you should be using double quotes exclusively.-PowerShell treats both single and double quotes as quotes.---File: hledger.info,  Node: Double escaping regular expression metacharacters,  Next: Triple escaping for add-on commands,  Prev: Single escaping shell metacharacters,  Up: Special characters--5.2.2 Double escaping (regular expression metacharacters)------------------------------------------------------------Characters significant in regular expressions (described below) - such-as '.', '^', '$', '[', ']', '(', ')', '|', and '\' - may need to be-"regex-escaped" if you don't want them to be interpreted by hledger's-regular expression engine.  This is done by writing backslashes before-them, but since backslash is typically also a shell metacharacter, both-shell-escaping and regex-escaping will be needed.  Eg to match a literal-'$' sign while using the bash shell:--$ hledger balance cur:'\$'--   or:--$ hledger balance cur:\\$---File: hledger.info,  Node: Triple escaping for add-on commands,  Next: Less escaping,  Prev: Double escaping regular expression metacharacters,  Up: Special characters--5.2.3 Triple escaping (for add-on commands)----------------------------------------------When you use hledger to run an external add-on command (described-below), one level of shell-escaping is lost from any options or-arguments intended for by the add-on command, so those need an extra-level of shell-escaping.  Eg to match a literal '$' sign while using the-bash shell and running an add-on command ('ui'):--$ hledger ui cur:'\\$'--   or:--$ hledger ui cur:\\\\$--   If you wondered why _four_ backslashes, perhaps this helps:--unescaped:        '$'-escaped:          '\$'-double-escaped:   '\\$'-triple-escaped:   '\\\\$'--   Or, you can avoid the extra escaping by running the add-on executable-directly:--$ hledger-ui cur:\\$---File: hledger.info,  Node: Less escaping,  Prev: Triple escaping for add-on commands,  Up: Special characters--5.2.4 Less escaping----------------------Options and arguments are sometimes used in places other than the shell-command line, where shell-escaping is not needed, so there you should-use one less level of escaping.  Those places include:--   * an @argumentfile-   * hledger-ui's filter field-   * hledger-web's search form-   * GHCI's prompt (used by developers).---File: hledger.info,  Node: Unicode characters,  Next: Regular expressions,  Prev: Special characters,  Up: Command line tips--5.3 Unicode characters-======================--hledger is expected to handle non-ascii characters correctly:--   * they should be parsed correctly in input files and on the command-     line, by all hledger tools (add, iadd, hledger-web's-     search/add/edit forms, etc.)--   * they should be displayed correctly by all hledger tools, and-     on-screen alignment should be preserved.--   This requires a well-configured environment.  Here are some tips:--   * A system locale must be configured, and it must be one that can-     decode the characters being used.  In bash, you can set a locale-     like this: 'export LANG=en_US.UTF-8'.  There are some more details-     in Troubleshooting.  This step is essential - without it, hledger-     will quit on encountering a non-ascii character (as with all-     GHC-compiled programs).--   * your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..)-     must support unicode--   * the terminal must be using a font which includes the required-     unicode glyphs--   * the terminal should be configured to display wide characters as-     double width (for report alignment)--   * on Windows, for best results you should run hledger in the same-     kind of environment in which it was built.  Eg hledger built in the-     standard CMD.EXE environment (like the binaries on our download-     page) might show display problems when run in a cygwin or msys-     terminal, and vice versa.  (See eg #961).---File: hledger.info,  Node: Regular expressions,  Next: Argument files,  Prev: Unicode characters,  Up: Command line tips--5.4 Regular expressions-=======================--A regular expression (regexp) is a small piece of text where certain-characters (like '.', '^', '$', '+', '*', '()', '|', '[]', '\') have-special meanings, forming a tiny language for matching text precisely --very useful in hledger and elsewhere.  To learn all about them, visit-regular-expressions.info.--   hledger supports regexps whenever you are entering a pattern to match-something, eg in query arguments, account aliases, CSV if rules,-hledger-web's search form, hledger-ui's '/' search, etc.  You may need-to wrap them in quotes, especially at the command line (see Special-characters above).  Here are some examples:--   Account name queries (quoted for command line use):--Regular expression:  Matches:--------------------  -------------------------------------------------------------bank                 assets:bank, assets:bank:savings, expenses:art:banksy, ...-:bank                assets:bank:savings, expenses:art:banksy-:bank:               assets:bank:savings-'^bank'              none of those ( ^ matches beginning of text )-'bank$'              assets:bank   ( $ matches end of text )-'big \$ bank'        big $ bank    ( \ disables following character's special meaning )-'\bbank\b'           assets:bank, assets:bank:savings  ( \b matches word boundaries )-'(sav|check)ing'     saving or checking  ( (|) matches either alternative )-'saving|checking'    saving or checking  ( outer parentheses are not needed )-'savings?'           saving or savings   ( ? matches 0 or 1 of the preceding thing )-'my +bank'           my bank, my  bank, ... ( + matches 1 or more of the preceding thing )-'my *bank'           mybank, my bank, my  bank, ... ( * matches 0 or more of the preceding thing )-'b.nk'               bank, bonk, b nk, ... ( . matches any character )--   Some other queries:--desc:'amazon|amzn|audible'  Amazon transactions-cur:EUR              amounts with commodity symbol containing EUR-cur:'\$'             amounts with commodity symbol containing $-cur:'^\$$'           only $ amounts, not eg AU$ or CA$-cur:....?            amounts with 4-or-more-character symbols-tag:.=202[1-3]       things with any tag whose value contains 2021, 2022 or 2023--   Account name aliases: accept '.' instead of ':' as account separator:--alias /\./=:         replaces all periods in account names with colons--   Show multiple top-level accounts combined as one:----alias='/^[^:]+/=combined'  ( [^:] matches any character other than : )--   Show accounts with the second-level part removed:----alias '/^([^:]+):[^:]+/ = \1'-                     match a top-level account and a second-level account-                     and replace those with just the top-level account-                     ( \1 in the replacement text means "whatever was matched-                     by the first parenthesised part of the regexp"--   CSV rules: match CSV records containing dining-related MCC codes:--if \?MCC581[124]--   Match CSV records with a specific amount around the end/start of-month:--if %amount \b3\.99-&  %date   (29|30|31|01|02|03)$--* Menu:--* hledger's regular expressions::---File: hledger.info,  Node: hledger's regular expressions,  Up: Regular expressions--5.4.1 hledger's regular expressions--------------------------------------hledger's regular expressions come from the regex-tdfa library.  If-they're not doing what you expect, it's important to know exactly what-they support:--  1. they are case insensitive-  2. they are infix matching (they do not need to match the entire thing-     being matched)-  3. they are POSIX ERE (extended regular expressions)-  4. they also support GNU word boundaries ('\b', '\B', '\<', '\>')-  5. backreferences are supported when doing text replacement in account-     aliases or CSV rules, where backreferences can be used in the-     replacement string to reference capturing groups in the search-     regexp.  Otherwise, if you write '\1', it will match the digit '1'.-  6. they do not support mode modifiers ('(?s)'), character classes-     ('\w', '\d'), or anything else not mentioned above.--   Some things to note:--   * In the 'alias' directive and '--alias' option, regular expressions-     must be enclosed in forward slashes ('/REGEX/').  Elsewhere in-     hledger, these are not required.--   * In queries, to match a regular expression metacharacter like '$' as-     a literal character, prepend a backslash.  Eg to search for amounts-     with the dollar sign in hledger-web, write 'cur:\$'.--   * On the command line, some metacharacters like '$' have a special-     meaning to the shell and so must be escaped at least once more.-     See Special characters.---File: hledger.info,  Node: Argument files,  Prev: Regular expressions,  Up: Command line tips--5.5 Argument files-==================--You can save a set of command line options and arguments in a file, and-then reuse them by writing '@FILENAME' as a command line argument.  Eg:-'hledger bal @foo.args'.--   Inside the argument file, each line should contain just one option or-argument.  Don't use spaces except inside quotes (or you'll see a-confusing error); write '=' (or nothing) between a flag and its-argument.  For the special characters mentioned above, use one less-level of quoting than you would at the command prompt.---File: hledger.info,  Node: Output,  Next: Environment,  Prev: Command line tips,  Up: Top--6 Output-********--* Menu:--* Output destination::-* Output format::-* Commodity styles::-* Colour::-* Box-drawing::-* Paging::-* Debug output::---File: hledger.info,  Node: Output destination,  Next: Output format,  Up: Output--6.1 Output destination-======================--hledger commands send their output to the terminal by default.  You can-of course redirect this, eg into a file, using standard shell syntax:--$ hledger print > foo.txt--   Some commands (print, register, stats, the balance commands) also-provide the '-o/--output-file' option, which does the same thing without-needing the shell.  Eg:--$ hledger print -o foo.txt-$ hledger print -o -        # write to stdout (the default)---File: hledger.info,  Node: Output format,  Next: Commodity styles,  Prev: Output destination,  Up: Output--6.2 Output format-=================--Some commands offer other kinds of output, not just text on the-terminal.  Here are those commands and the formats currently supported:---                 txt             csv/tsv         html              json  sql---------------------------------------------------------------------------------aregister         Y               Y               Y                 Y-balance           Y _1_           Y _1_           Y _1,2_           Y-balancesheet      Y _1_           Y _1_           Y _1_             Y-balancesheetequityY _1_           Y _1_           Y _1_             Y-cashflow          Y _1_           Y _1_           Y _1_             Y-incomestatement   Y _1_           Y _1_           Y _1_             Y-print             Y               Y                                 Y     Y-register          Y               Y                                 Y--   * _1 Also affected by the balance commands' '--layout' option._-   * _2 'balance' does not support html output without a report interval-     or with '--budget'._--   The output format is selected by the '-O/--output-format=FMT' option:--$ hledger print -O csv    # print CSV on stdout--   or by the filename extension of an output file specified with the-'-o/--output-file=FILE.FMT' option:--$ hledger balancesheet -o foo.csv    # write CSV to foo.csv--   The '-O' option can be combined with '-o' to override the file-extension, if needed:--$ hledger balancesheet -o foo.txt -O csv    # write CSV to foo.txt--   Some notes about the various output formats:--* Menu:--* CSV output::-* HTML output::-* JSON output::-* SQL output::---File: hledger.info,  Node: CSV output,  Next: HTML output,  Up: Output format--6.2.1 CSV output-------------------   * In CSV output, digit group marks (such as thousands separators) are-     disabled automatically.---File: hledger.info,  Node: HTML output,  Next: JSON output,  Prev: CSV output,  Up: Output format--6.2.2 HTML output--------------------   * HTML output can be styled by an optional 'hledger.css' file in the-     same directory.---File: hledger.info,  Node: JSON output,  Next: SQL output,  Prev: HTML output,  Up: Output format--6.2.3 JSON output--------------------   * This is not yet much used; real-world feedback is welcome.--   * Our JSON is rather large and verbose, since it is a faithful-     representation of hledger's internal data types.  To understand the-     JSON, read the Haskell type definitions, which are mostly in-     https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs.--   * hledger represents quantities as Decimal values storing up to 255-     significant digits, eg for repeating decimals.  Such numbers can-     arise in practice (from automatically-calculated transaction-     prices), and would break most JSON consumers.  So in JSON, we show-     quantities as simple Numbers with at most 10 decimal places.  We-     don't limit the number of integer digits, but that part is under-     your control.  We hope this approach will not cause problems in-     practice; if you find otherwise, please let us know.  (Cf #1195)---File: hledger.info,  Node: SQL output,  Prev: JSON output,  Up: Output format--6.2.4 SQL output-------------------   * This is not yet much used; real-world feedback is welcome.--   * SQL output is expected to work at least with SQLite, MySQL and-     Postgres.--   * For SQLite, it will be more useful if you modify the generated 'id'-     field to be a PRIMARY KEY. Eg:--     $ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ...--   * SQL output is structured with the expectations that statements will-     be executed in the empty database.  If you already have tables-     created via SQL output of hledger, you would probably want to-     either clear tables of existing data (via 'delete' or 'truncate'-     SQL statements) or drop tables completely as otherwise your-     postings will be duped.---File: hledger.info,  Node: Commodity styles,  Next: Colour,  Prev: Output format,  Up: Output--6.3 Commodity styles-====================--When displaying amounts, hledger infers a standard display style for-each commodity/currency, as described below in Commodity display style.--   If needed, this can be overridden by a '-c/--commodity-style' option-(except for cost amounts and amounts displayed by the 'print' command,-which are always displayed with all decimal digits).  For example, the-following will force dollar amounts to be displayed as shown:--$ hledger print -c '$1.000,0'--   This option can repeated to set the display style for multiple-commodities/currencies.  Its argument is as described in the commodity-directive.---File: hledger.info,  Node: Colour,  Next: Box-drawing,  Prev: Commodity styles,  Up: Output--6.4 Colour-==========--In terminal output, some commands can produce colour when the terminal-supports it:--   * if the '--color/--colour' option is given a value of 'yes' or-     'always' (or 'no' or 'never'), colour will (or will not) be used;-   * otherwise, if the 'NO_COLOR' environment variable is set, colour-     will not be used;-   * otherwise, colour will be used if the output (terminal or file)-     supports it.---File: hledger.info,  Node: Box-drawing,  Next: Paging,  Prev: Colour,  Up: Output--6.5 Box-drawing-===============--In terminal output, you can enable unicode box-drawing characters to-render prettier tables:--   * if the '--pretty' option is given a value of 'yes' or 'always' (or-     'no' or 'never'), unicode characters will (or will not) be used;-   * otherwise, unicode characters will not be used.---File: hledger.info,  Node: Paging,  Next: Debug output,  Prev: Box-drawing,  Up: Output--6.6 Paging-==========--When showing long output in the terminal, hledger will try to use the-pager specified by the 'PAGER' environment variable, or 'less', or-'more'.  (A pager is a helper program that shows one page at a time-rather than scrolling everything off screen).  Currently it does this-only for help output, not for reports; specifically,--   * when listing commands, with 'hledger'-   * when showing help with 'hledger [CMD] --help',-   * when viewing manuals with 'hledger help' or 'hledger --man'.--   Note the pager is expected to handle ANSI codes, which hledger uses-eg for bold emphasis.  For the common pager 'less' (and its 'more'-compatibility mode), we add 'R' to the 'LESS' and 'MORE' environment-variables to make this work.  If you use a different pager, you might-need to configure it similarly, to avoid seeing junk on screen (let us-know).  Otherwise, you can set the 'NO_COLOR' environment variable to 1-to disable all ANSI output (see Colour).---File: hledger.info,  Node: Debug output,  Prev: Paging,  Up: Output--6.7 Debug output-================--We intend hledger to be relatively easy to troubleshoot, introspect and-develop.  You can add '--debug[=N]' to any hledger command line to see-additional debug output.  N ranges from 1 (least output, the default) to-9 (maximum output).  Typically you would start with 1 and increase until-you are seeing enough.  Debug output goes to stderr, and is not affected-by '-o/--output-file' (unless you redirect stderr to stdout, eg:-'2>&1').  It will be interleaved with normal output, which can help-reveal when parts of the code are evaluated.  To capture debug output in-a log file instead, you can usually redirect stderr, eg:--hledger bal --debug=3 2>hledger.log---File: hledger.info,  Node: Environment,  Next: PART 2 DATA FORMATS,  Prev: Output,  Up: Top--7 Environment-*************--These environment variables affect hledger:--   *COLUMNS* This is normally set by your terminal; some hledger-commands ('register') will format their output to this width.  If not-set, they will try to use the available terminal width.--   *LEDGER_FILE* The main journal file to use when not specified with-'-f/--file'.  Default: '$HOME/.hledger.journal'.--   *NO_COLOR* If this environment variable is set (with any value),-hledger will not use ANSI color codes in terminal output, unless-overridden by an explicit '--color/--colour' option.---File: hledger.info,  Node: PART 2 DATA FORMATS,  Next: Journal,  Prev: Environment,  Up: Top--8 PART 2: DATA FORMATS-**********************---File: hledger.info,  Node: Journal,  Next: CSV,  Prev: PART 2 DATA FORMATS,  Up: Top--9 Journal-*********--hledger's default file format, representing a General Journal.  Here's a-cheatsheet/mini-tutorial, or you can skip ahead to About journal format.--* Menu:--* Journal cheatsheet::-* About journal format::-* Comments::-* Transactions::-* Dates::-* Status::-* Code::-* Description::-* Transaction comments::-* Postings::-* Account names::-* Amounts::-* Costs::-* Balance assertions::-* Posting comments::-* Tags::-* Directives::-* account directive::-* alias directive::-* commodity directive::-* decimal-mark directive::-* include directive::-* P directive::-* payee directive::-* tag directive::-* Periodic transactions::-* Auto postings::-* Other syntax::---File: hledger.info,  Node: Journal cheatsheet,  Next: About journal format,  Up: Journal--9.1 Journal cheatsheet-======================--# Here is the main syntax of hledger's journal format-# (omitting extra Ledger compatibility syntax).-# hledger journals contain comments, directives, and transactions, in any order:--###############################################################################-# 1. Comment lines are for notes or temporarily disabling things.-# They begin with #, ;, or a line containing the word "comment".--# hash comment line-; semicolon comment line-comment-These lines-are commented.-end comment--# Some but not all hledger entries can have same-line comments attached to them,-# from ; (semicolon) to end of line.--###############################################################################-# 2. Directives modify parsing or reports in some way.-# They begin with a word or letter (or symbol).--account actifs     ; type:A, declare an account that is an Asset. 2+ spaces before ;.-account passifs    ; type:L, declare an account that is a Liability, and so on.. (ALERX)-alias chkg = assets:checking-commodity $0.00-decimal-mark .-include /dev/null-payee Whole Foods-P 2022-01-01 AAAA $1.40-~ monthly    budget goals  ; <- 2+ spaces between period expression and description-    expenses:food       $400-    expenses:home      $1000-    budgeted--###############################################################################-# 3. Transactions are what it's all about; they are dated events,-# usually describing movements of money.-# They begin with a date.--# DATE DESCRIPTION           ; This is a transaction comment.-#   ACCOUNT NAME 1  AMOUNT1  ; <- posting 1. This is a posting comment.-#   ACCOUNT NAME 2  AMOUNT2  ; <- posting 2. Postings must be indented.-#               ; ^^ At least 2 spaces between account and amount.-#   ...  ; Any number of postings is allowed. The amounts must balance (sum to 0).--2022-01-01 opening balances are declared this way-    assets:checking          $1000  ; Account names can be anything. lower case is easy to type.-    assets:savings           $1000  ; assets, liabilities, equity, revenues, expenses are common.-    assets:cash:wallet        $100  ; : indicates subaccounts.-    liabilities:credit card  $-200  ; liabilities, equity, revenues balances are usually negative.-    equity                          ; One amount can be left blank; $-1900 is inferred here.--2022-04-15 * (#12345) pay taxes-    ; There can be a ! or * after the date meaning "pending" or "cleared".-    ; There can be a transaction code (text in parentheses) after the date/status.-    ; Amounts' sign represents direction of flow, or credit/debit:-    assets:checking          $-500  ; minus means removed from this account (credit)-    expenses:tax:us:2021      $500  ; plus  means added to this account (debit)-                                    ; revenue/expense categories are also "accounts"--2022-01-01                          ; The description is optional.-    ; Any currency/commodity symbols are allowed, on either side.-    assets:cash:wallet     GBP -10-    expenses:clothing       GBP 10-    assets:gringotts           -10 gold-    assets:pouch                10 gold-    revenues:gifts              -2 "Liquorice Wands"  ; Complex symbols-    assets:bag                   2 "Liquorice Wands"  ; must be double-quoted.--2022-01-01 Cost in another commodity can be noted with @ or @@-    assets:investments           2.0 AAAA @ $1.50  ; @  means per-unit cost-    assets:investments           3.0 AAAA @@ $4    ; @@ means total cost-    assets:checking            $-7.00--2022-01-02 assert balances-    ; Balances can be asserted for extra error checking, in any transaction.-    assets:investments           0 AAAA = 5.0 AAAA-    assets:pouch                 0 gold = 10 gold-    assets:savings              $0      = $1000--1999-12-31 Ordering transactions by date is recommended but not required.-    ; Postings are not required.--2022.01.01 These date-2022/1/1   formats are-12/31      also allowed (but consistent YYYY-MM-DD is recommended).---File: hledger.info,  Node: About journal format,  Next: Comments,  Prev: Journal cheatsheet,  Up: Journal--9.2 About journal format-========================--hledger's usual data source is a plain text file containing journal-entries in hledger journal format.  This file represents a standard-accounting general journal.  I use file names ending in '.journal', but-that's not required.  The journal file contains a number of transaction-entries, each describing a transfer of money (or any commodity) between-two or more named accounts, in a simple format readable by both hledger-and humans.--   hledger's journal format is compatible with most of Ledger's journal-format, but not all of it.  The differences and interoperation tips are-described at hledger and Ledger.  With some care, and by avoiding-incompatible features, you can keep your hledger journal readable by-Ledger and vice versa.  This can useful eg for comparing the behaviour-of one app against the other.--   You can use hledger without learning any more about this file; just-use the add or web or import commands to create and update it.--   Many users, though, edit the journal file with a text editor, and-track changes with a version control system such as git.  Editor addons-such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and-hledger-vscode for Visual Studio Code, make this easier, adding colour,-formatting, tab completion, and useful commands.  See Editor-configuration at hledger.org for the full list.--   Here's a description of each part of the file format (and hledger's-data model).--   A hledger journal file can contain three kinds of thing: file-comments, transactions, and/or directives (counting periodic transaction-rules and auto posting rules as directives).---File: hledger.info,  Node: Comments,  Next: Transactions,  Prev: About journal format,  Up: Journal--9.3 Comments-============--Lines in the journal will be ignored if they begin with a hash ('#') or-a semicolon (';').  (See also Other syntax.)  hledger will also ignore-regions beginning with a 'comment' line and ending with an 'end comment'-line (or file end).  Here's a suggestion for choosing between them:--   * '#' for top-level notes-   * ';' for commenting out things temporarily-   * 'comment' for quickly commenting large regions (remember it's-     there, or you might get confused)--   Eg:--# a comment line-; another commentline-comment-A multi-line comment block,-continuing until "end comment" directive-or the end of the current file.-end comment--   Some hledger entries can have same-line comments attached to them,-from ; (semicolon) to end of line.  See Transaction comments, Posting-comments, and Account comments below.---File: hledger.info,  Node: Transactions,  Next: Dates,  Prev: Comments,  Up: Journal--9.4 Transactions-================--Transactions are the main unit of information in a journal file.  They-represent events, typically a movement of some quantity of commodities-between two or more named accounts.--   Each transaction is recorded as a journal entry, beginning with a-simple date in column 0.  This can be followed by any of the following-optional fields, separated by spaces:--   * a status character (empty, '!', or '*')-   * a code (any short number or text, enclosed in parentheses)-   * a description (any remaining text until end of line or a semicolon)-   * a comment (any remaining text following a semicolon until end of-     line, and any following indented lines beginning with a semicolon)-   * 0 or more indented _posting_ lines, describing what was transferred-     and the accounts involved (indented comment lines are also allowed,-     but not blank lines or non-indented lines).--   Here's a simple journal file containing one transaction:--2008/01/01 income-  assets:bank:checking   $1-  income:salary         $-1---File: hledger.info,  Node: Dates,  Next: Status,  Prev: Transactions,  Up: Journal--9.5 Dates-=========--* Menu:--* Simple dates::-* Posting dates::---File: hledger.info,  Node: Simple dates,  Next: Posting dates,  Up: Dates--9.5.1 Simple dates---------------------Dates in the journal file use _simple dates_ format: 'YYYY-MM-DD' or-'YYYY/MM/DD' or 'YYYY.MM.DD', with leading zeros optional.  The year may-be omitted, in which case it will be inferred from the context: the-current transaction, the default year set with a 'Y' directive, or the-current date when the command is run.  Some examples: '2010-01-31',-'2010/01/31', '2010.1.31', '1/31'.--   (The UI also accepts simple dates, as well as the more flexible smart-dates documented in the hledger manual.)---File: hledger.info,  Node: Posting dates,  Prev: Simple dates,  Up: Dates--9.5.2 Posting dates----------------------You can give individual postings a different date from their parent-transaction, by adding a posting comment containing a tag (see below)-like 'date:DATE'.  This is probably the best way to control posting-dates precisely.  Eg in this example the expense should appear in May-reports, and the deduction from checking should be reported on 6/1 for-easy bank reconciliation:--2015/5/30-    expenses:food     $10  ; food purchased on saturday 5/30-    assets:checking        ; bank cleared it on monday, date:6/1--$ hledger -f t.j register food-2015-05-30                      expenses:food                  $10           $10--$ hledger -f t.j register checking-2015-06-01                      assets:checking               $-10          $-10--   DATE should be a simple date; if the year is not specified it will-use the year of the transaction's date.-The 'date:' tag must have a valid simple date value if it is present, eg-a 'date:' tag with no value is not allowed.---File: hledger.info,  Node: Status,  Next: Code,  Prev: Dates,  Up: Journal--9.6 Status-==========--Transactions, or individual postings within a transaction, can have a-status mark, which is a single character before the transaction-description or posting account name, separated from it by a space,-indicating one of three statuses:--mark  status- -------------------      unmarked-'!'   pending-'*'   cleared--   When reporting, you can filter by status with the '-U/--unmarked',-'-P/--pending', and '-C/--cleared' flags; or the 'status:', 'status:!',-and 'status:*' queries; or the U, P, C keys in hledger-ui.--   Note, in Ledger and in older versions of hledger, the "unmarked"-state is called "uncleared".  As of hledger 1.3 we have renamed it to-unmarked for clarity.--   To replicate Ledger and old hledger's behaviour of also matching-pending, combine -U and -P.--   Status marks are optional, but can be helpful eg for reconciling with-real-world accounts.  Some editor modes provide highlighting and-shortcuts for working with status.  Eg in Emacs ledger-mode, you can-toggle transaction status with C-c C-e, or posting status with C-c C-c.--   What "uncleared", "pending", and "cleared" actually mean is up to-you.  Here's one suggestion:--status     meaning----------------------------------------------------------------------------uncleared  recorded but not yet reconciled; needs review-pending    tentatively reconciled (if needed, eg during a big-           reconciliation)-cleared    complete, reconciled as far as possible, and considered-           correct--   With this scheme, you would use '-PC' to see the current balance at-your bank, '-U' to see things which will probably hit your bank soon-(like uncashed checks), and no flags to see the most up-to-date state of-your finances.---File: hledger.info,  Node: Code,  Next: Description,  Prev: Status,  Up: Journal--9.7 Code-========--After the status mark, but before the description, you can optionally-write a transaction "code", enclosed in parentheses.  This is a good-place to record a check number, or some other important transaction id-or reference number.---File: hledger.info,  Node: Description,  Next: Transaction comments,  Prev: Code,  Up: Journal--9.8 Description-===============--A transaction's description is the rest of the line following the date-and status mark (or until a comment begins).  Sometimes called the-"narration" in traditional bookkeeping, it can be used for whatever you-wish, or left blank.  Transaction descriptions can be queried, unlike-comments.--* Menu:--* Payee and note::---File: hledger.info,  Node: Payee and note,  Up: Description--9.8.1 Payee and note-----------------------You can optionally include a '|' (pipe) character in descriptions to-subdivide the description into separate fields for payee/payer name on-the left (up to the first '|') and an additional note field on the right-(after the first '|').  This may be worthwhile if you need to do more-precise querying and pivoting by payee or by note.---File: hledger.info,  Node: Transaction comments,  Next: Postings,  Prev: Description,  Up: Journal--9.9 Transaction comments-========================--Text following ';', after a transaction description, and/or on indented-lines immediately below it, form comments for that transaction.  They-are reproduced by 'print' but otherwise ignored, except they may contain-tags, which are not ignored.--2012-01-01 something  ; a transaction comment-    ; a second line of transaction comment-    expenses   1-    assets---File: hledger.info,  Node: Postings,  Next: Account names,  Prev: Transaction comments,  Up: Journal--9.10 Postings-=============--A posting is an addition of some amount to, or removal of some amount-from, an account.  Each posting line begins with at least one space or-tab (2 or 4 spaces is common), followed by:--   * (optional) a status character (empty, '!', or '*'), followed by a-     space-   * (required) an account name (any text, optionally containing *single-     spaces*, until end of line or a double space)-   * (optional) *two or more spaces* or tabs followed by an amount.--   Positive amounts are being added to the account, negative amounts are-being removed.--   The amounts within a transaction must always sum up to zero.  As a-convenience, one amount may be left blank; it will be inferred so as to-balance the transaction.--   Be sure to note the unusual two-space delimiter between account name-and amount.  This makes it easy to write account names containing-spaces.  But if you accidentally leave only one space (or tab) before-the amount, the amount will be considered part of the account name.---File: hledger.info,  Node: Account names,  Next: Amounts,  Prev: Postings,  Up: Journal--9.11 Account names-==================--Accounts are the main way of categorising things in hledger.  As in-Double Entry Bookkeeping, they can represent real world accounts (such-as a bank account), or more abstract categories such as "money borrowed-from Frank" or "money spent on electricity".--   You can use any account names you like, but we usually start with the-traditional accounting categories, which in english are 'assets',-'liabilities', 'equity', 'revenues', 'expenses'.  (You might see these-referred to as A, L, E, R, X for short.)--   For more precise reporting, we usually divide the top level accounts-into more detailed subaccounts, by writing a full colon between account-name parts.  For example, from the account names 'assets:bank:checking'-and 'expenses:food', hledger will infer this hierarchy of five accounts:--assets-assets:bank-assets:bank:checking-expenses-expenses:food--   Shown as an outline, the hierarchical tree structure is more clear:--assets- bank-  checking-expenses- food--   hledger reports can summarise the account tree to any depth, so you-can go as deep as you like with subcategories, but keeping your account-names relatively simple may be best when starting out.--   Account names may be capitalised or not; they may contain letters,-numbers, symbols, or single spaces.  Note, when an account name and an-amount are written on the same line, they must be separated by *two or-more spaces* (or tabs).--   Parentheses or brackets enclosing the full account name indicate-virtual postings, described below.  Parentheses or brackets internal to-the account name have no special meaning.--   Account names can be altered temporarily or permanently by account-aliases.---File: hledger.info,  Node: Amounts,  Next: Costs,  Prev: Account names,  Up: Journal--9.12 Amounts-============--After the account name, there is usually an amount.  (Important: between-account name and amount, there must be *two or more spaces*.)--   hledger's amount format is flexible, supporting several international-formats.  Here are some examples.  Amounts have a number (the-"quantity"):--1--   ..and usually a currency symbol or commodity name (more on this-below), to the left or right of the quantity, with or without a-separating space:--$1-4000 AAPL-3 "green apples"--   Amounts can be preceded by a minus sign (or a plus sign, though plus-is the default), The sign can be written before or after a left-side-commodity symbol:---$1-$-1--   One or more spaces between the sign and the number are acceptable-when parsing (but they won't be displayed in output):--+ $1-$-      1--   Scientific E notation is allowed:--1E-6-EUR 1E3--* Menu:--* Decimal marks digit group marks::-* Commodity::-* Directives influencing number parsing and display::-* Commodity display style::-* Rounding::---File: hledger.info,  Node: Decimal marks digit group marks,  Next: Commodity,  Up: Amounts--9.12.1 Decimal marks, digit group marks------------------------------------------A _decimal mark_ can be written as a period or a comma:--1.23-1,23--   In the integer part of the quantity (left of the decimal mark),-groups of digits can optionally be separated by a _digit group mark_ - a-space, comma, or period (different from the decimal mark):--     $1,000,000.00-  EUR 2.000.000,00-INR 9,99,99,999.00-      1 000 000.9455--   hledger is not biased towards period or comma decimal marks, so a-number containing just one period or comma, like '1,000' or '1.000', is-ambiguous.  In such cases hledger assumes it is a decimal mark, parsing-both of these as 1.--   To disambiguate these and ensure accurate number parsing, especially-if you use digit group marks, we recommend declaring the decimal mark.-You can declare it for each file with 'decimal-mark' directives, or for-each commodity with 'commodity' directives (described below).---File: hledger.info,  Node: Commodity,  Next: Directives influencing number parsing and display,  Prev: Decimal marks digit group marks,  Up: Amounts--9.12.2 Commodity-------------------Amounts in hledger have both a "quantity", which is a signed decimal-number, and a "commodity", which is a currency symbol, stock ticker, or-any word or phrase describing something you are tracking.--   If the commodity name contains non-letters (spaces, numbers, or-punctuation), you must always write it inside double quotes ('"green-apples"', '"ABC123"').--   If you write just a bare number, that too will have a commodity, with-name '""'; we call that the "no-symbol commodity".--   Actually, hledger combines these single-commodity amounts into more-powerful multi-commodity amounts, which are what it works with most of-the time.  A multi-commodity amount could be, eg: '1 USD, 2 EUR, 3.456-TSLA'.  In practice, you will only see multi-commodity amounts in-hledger's output; you can't write them directly in the journal file.--   (If you are writing scripts or working with hledger's internals,-these are the 'Amount' and 'MixedAmount' types.)---File: hledger.info,  Node: Directives influencing number parsing and display,  Next: Commodity display style,  Prev: Commodity,  Up: Amounts--9.12.3 Directives influencing number parsing and display-----------------------------------------------------------You can add 'decimal-mark' and 'commodity' directives to the journal, to-declare and control these things more explicitly and precisely.  These-are described below, but here's a quick example:--# the decimal mark character used by all amounts in this file (all commodities)-decimal-mark .--# display styles for the $, EUR, INR and no-symbol commodities:-commodity $1,000.00-commodity EUR 1.000,00-commodity INR 9,99,99,999.00-commodity 1 000 000.9455---File: hledger.info,  Node: Commodity display style,  Next: Rounding,  Prev: Directives influencing number parsing and display,  Up: Amounts--9.12.4 Commodity display style---------------------------------For the amounts in each commodity, hledger chooses a consistent display-style (symbol placement, decimal mark and digit group marks, number of-decimal digits) to use in most reports.  This is inferred as follows:--   First, if there's a 'D' directive declaring a default commodity, that-commodity symbol and amount format is applied to all no-symbol amounts-in the journal.--   Then each commodity's display style is determined from its-'commodity' directive.  We recommend always declaring commodities with-'commodity' directives, since they help ensure consistent display styles-and precisions, and bring other benefits such as error checking for-commodity symbols.--   But if a 'commodity' directive is not present, hledger infers a-commodity's display styles from its amounts as they are written in the-journal (excluding cost amounts and amounts in periodic transaction-rules or auto posting rules).  It uses--   * the symbol placement and decimal mark of the first amount seen-   * the digit group marks of the first amount with digit group marks-   * and the maximum number of decimal digits seen across all amounts.--   And as fallback if no applicable amounts are found, it would use a-default style, like '$1000.00' (symbol on the left with no space, period-as decimal mark, and two decimal digits).--   Finally, commodity styles can be overridden by the-'-c/--commodity-style' command line option.---File: hledger.info,  Node: Rounding,  Prev: Commodity display style,  Up: Amounts--9.12.5 Rounding------------------Amounts are stored internally as decimal numbers with up to 255 decimal-places.  They are displayed with their original journal precisions by-print and print-like reports, and rounded to their display precision-(the number of decimal digits specified by the commodity display style)-by other reports.  When rounding, hledger uses banker's rounding (it-rounds to the nearest even digit).  So eg 0.5 displayed with zero-decimal digits appears as "0".---File: hledger.info,  Node: Costs,  Next: Balance assertions,  Prev: Amounts,  Up: Journal--9.13 Costs-==========--After a posting amount, you can note its cost (when buying) or selling-price (when selling) in another commodity, by writing either '@-UNITPRICE' or '@@ TOTALPRICE' after it.  This indicates a conversion-transaction, where one commodity is exchanged for another.--   (You might also see this called "transaction price" in hledger docs,-discussions, or code; that term was directionally neutral and reminded-that it is a price specific to a transaction, but we now just call it-"cost", with the understanding that the transaction could be a purchase-or a sale.)--   Costs are usually written explicitly with '@' or '@@', but can also-be inferred automatically for simple multi-commodity transactions.-Note, if costs are inferred, the order of postings is significant; the-first posting will have a cost attached, in the commodity of the second.--   As an example, here are several ways to record purchases of a foreign-currency in hledger, using the cost notation either explicitly or-implicitly:--  1. Write the price per unit, as '@ UNITPRICE' after the amount:--     2009/1/1-       assets:euros     €100 @ $1.35  ; one hundred euros purchased at $1.35 each-       assets:dollars                 ; balancing amount is -$135.00--  2. Write the total price, as '@@ TOTALPRICE' after the amount:--     2009/1/1-       assets:euros     €100 @@ $135  ; one hundred euros purchased at $135 for the lot-       assets:dollars--  3. Specify amounts for all postings, using exactly two commodities,-     and let hledger infer the price that balances the transaction.-     Note the effect of posting order: the price is added to first-     posting, making it '€100 @@ $135', as in example 2:--     2009/1/1-       assets:euros     €100          ; one hundred euros purchased-       assets:dollars  $-135          ; for $135--   Amounts can be converted to cost at report time using the '-B/--cost'-flag; this is discussed more in the Cost reporting section.--   Note that the cost normally should be a positive amount, though it's-not required to be.  This can be a little confusing, see discussion at--infer-market-prices: market prices from transactions.--* Menu:--* Other cost/lot notations::---File: hledger.info,  Node: Other cost/lot notations,  Up: Costs--9.13.1 Other cost/lot notations----------------------------------A slight digression for Ledger and Beancount users.  Ledger has a number-of cost/lot-related notations:--   * '@ UNITCOST' and '@@ TOTALCOST'-        * expresses a conversion rate, as in hledger-        * when buying, also creates a lot than can be selected at-          selling time--   * '(@) UNITCOST' and '(@@) TOTALCOST' (virtual cost)-        * like the above, but also means "this cost was exceptional,-          don't use it when inferring market prices".--   Currently, hledger treats the above like '@' and '@@'; the-parentheses are ignored.--   * '{=FIXEDUNITCOST}' and '{{=FIXEDTOTALCOST}}' (fixed price)-        * when buying, means "this cost is also the fixed price, don't-          let it fluctuate in value reports"--   * '{UNITCOST}' and '{{TOTALCOST}}' (lot price)-        * can be used identically to '@ UNITCOST' and '@@ TOTALCOST',-          also creates a lot-        * when selling, combined with '@ ...', specifies an investment-          lot by its cost basis; does not check if that lot is present--   * and related: '[YYYY/MM/DD]' (lot date)-        * when buying, attaches this acquisition date to the lot-        * when selling, selects a lot by its acquisition date--   * '(SOME TEXT)' (lot note)-        * when buying, attaches this note to the lot-        * when selling, selects a lot by its note--   Currently, hledger accepts any or all of the above in any order after-the posting amount, but ignores them.  (This can break transaction-balancing.)--   For Beancount users, the notation and behaviour is different:--   * '@ UNITCOST' and '@@ TOTALCOST'-        * expresses a cost without creating a lot, as in hledger-        * when buying (augmenting) or selling (reducing) a lot, combined-          with '{...}': documents the cost/selling price (not used for-          transaction balancing)--   * '{UNITCOST}' and '{{TOTALCOST}}'-        * when buying (augmenting), expresses the cost for transaction-          balancing, and also creates a lot with this cost basis-          attached-        * when selling (reducing),-             * selects a lot by its cost basis-             * raises an error if that lot is not present or can not be-               selected unambiguously (depending on booking method-               configured)-             * expresses the selling price for transaction balancing--   Currently, hledger accepts the '{UNITCOST}'/'{{TOTALCOST}}' notation-but ignores it.--   * variations: '{}', '{YYYY-MM-DD}', '{"LABEL"}', '{UNITCOST,-     "LABEL"}', '{UNITCOST, YYYY-MM-DD, "LABEL"}' etc.--   Currently, hledger rejects these.---File: hledger.info,  Node: Balance assertions,  Next: Posting comments,  Prev: Costs,  Up: Journal--9.14 Balance assertions-=======================--hledger supports Ledger-style balance assertions in journal files.-These look like, for example, '= EXPECTEDBALANCE' following a posting's-amount.  Eg here we assert the expected dollar balance in accounts a and-b after each posting:--2013/1/1-  a   $1  =$1-  b       =$-1--2013/1/2-  a   $1  =$2-  b  $-1  =$-2--   After reading a journal file, hledger will check all balance-assertions and report an error if any of them fail.  Balance assertions-can protect you from, eg, inadvertently disrupting reconciled balances-while cleaning up old entries.  You can disable them temporarily with-the '-I/--ignore-assertions' flag, which can be useful for-troubleshooting or for reading Ledger files.  (Note: this flag currently-does not disable balance assignments, described below).--* Menu:--* Assertions and ordering::-* Assertions and multiple included files::-* Assertions and multiple -f files::-* Assertions and commodities::-* Assertions and prices::-* Assertions and subaccounts::-* Assertions and virtual postings::-* Assertions and auto postings::-* Assertions and precision::---File: hledger.info,  Node: Assertions and ordering,  Next: Assertions and multiple included files,  Up: Balance assertions--9.14.1 Assertions and ordering---------------------------------hledger sorts an account's postings and assertions first by date and-then (for postings on the same day) by parse order.  Note this is-different from Ledger, which sorts assertions only by parse order.-(Also, Ledger assertions do not see the accumulated effect of repeated-postings to the same account within a transaction.)--   So, hledger balance assertions keep working if you reorder-differently-dated transactions within the journal.  But if you reorder-same-dated transactions or postings, assertions might break and require-updating.  This order dependence does bring an advantage: precise-control over the order of postings and assertions within a day, so you-can assert intra-day balances.---File: hledger.info,  Node: Assertions and multiple included files,  Next: Assertions and multiple -f files,  Prev: Assertions and ordering,  Up: Balance assertions--9.14.2 Assertions and multiple included files------------------------------------------------Multiple files included with the 'include' directive are processed as if-concatenated into one file, preserving their order and the posting order-within each file.  It means that balance assertions in later files will-see balance from earlier files.--   And if you have multiple postings to an account on the same day,-split across multiple files, and you want to assert the account's-balance on that day, you'll need to put the assertion in the right file-- the last one in the sequence, probably.---File: hledger.info,  Node: Assertions and multiple -f files,  Next: Assertions and commodities,  Prev: Assertions and multiple included files,  Up: Balance assertions--9.14.3 Assertions and multiple -f files------------------------------------------Unlike 'include', when multiple files are specified on the command line-with multiple '-f/--file' options, balance assertions will not see-balance from earlier files.  This can be useful when you do not want-problems in earlier files to disrupt valid assertions in later files.--   If you do want assertions to see balance from earlier files, use-'include', or concatenate the files temporarily.---File: hledger.info,  Node: Assertions and commodities,  Next: Assertions and prices,  Prev: Assertions and multiple -f files,  Up: Balance assertions--9.14.4 Assertions and commodities------------------------------------The asserted balance must be a simple single-commodity amount, and in-fact the assertion checks only this commodity's balance within the-(possibly multi-commodity) account balance.  This is how assertions work-in Ledger also.  We could call this a "partial" balance assertion.--   To assert the balance of more than one commodity in an account, you-can write multiple postings, each asserting one commodity's balance.--   You can make a stronger "total" balance assertion by writing a double-equals sign ('== EXPECTEDBALANCE').  This asserts that there are no-other commodities in the account besides the asserted one (or at least,-that their balance is 0).--2013/1/1-  a   $1-  a    1€-  b  $-1-  c   -1€--2013/1/2  ; These assertions succeed-  a    0  =  $1-  a    0  =   1€-  b    0 == $-1-  c    0 ==  -1€--2013/1/3  ; This assertion fails as 'a' also contains 1€-  a    0 ==  $1--   It's not yet possible to make a complete assertion about a balance-that has multiple commodities.  One workaround is to isolate each-commodity into its own subaccount:--2013/1/1-  a:usd   $1-  a:euro   1€-  b--2013/1/2-  a        0 ==  0-  a:usd    0 == $1-  a:euro   0 ==  1€---File: hledger.info,  Node: Assertions and prices,  Next: Assertions and subaccounts,  Prev: Assertions and commodities,  Up: Balance assertions--9.14.5 Assertions and prices-------------------------------Balance assertions ignore costs, and should normally be written without-one:--2019/1/1-  (a)     $1 @ €1 = $1--   We do allow prices to be written there, however, and print shows-them, even though they don't affect whether the assertion passes or-fails.  This is for backward compatibility (hledger's close command used-to generate balance assertions with prices), and because balance-_assignments_ do use them (see below).---File: hledger.info,  Node: Assertions and subaccounts,  Next: Assertions and virtual postings,  Prev: Assertions and prices,  Up: Balance assertions--9.14.6 Assertions and subaccounts------------------------------------The balance assertions above ('=' and '==') do not count the balance-from subaccounts; they check the account's exclusive balance only.  You-can assert the balance including subaccounts by writing '=*' or '==*',-eg:--2019/1/1-  equity:opening balances-  checking:a       5-  checking:b       5-  checking         1  ==* 11---File: hledger.info,  Node: Assertions and virtual postings,  Next: Assertions and auto postings,  Prev: Assertions and subaccounts,  Up: Balance assertions--9.14.7 Assertions and virtual postings-----------------------------------------Balance assertions always consider both real and virtual postings; they-are not affected by the '--real/-R' flag or 'real:' query.---File: hledger.info,  Node: Assertions and auto postings,  Next: Assertions and precision,  Prev: Assertions and virtual postings,  Up: Balance assertions--9.14.8 Assertions and auto postings--------------------------------------Balance assertions _are_ affected by the '--auto' flag, which generates-auto postings, which can alter account balances.  Because auto postings-are optional in hledger, accounts affected by them effectively have two-balances.  But balance assertions can only test one or the other of-these.  So to avoid making fragile assertions, either:--   * assert the balance calculated with '--auto', and always use-     '--auto' with that file-   * or assert the balance calculated without '--auto', and never use-     '--auto' with that file-   * or avoid balance assertions on accounts affected by auto postings-     (or avoid auto postings entirely).---File: hledger.info,  Node: Assertions and precision,  Prev: Assertions and auto postings,  Up: Balance assertions--9.14.9 Assertions and precision----------------------------------Balance assertions compare the exactly calculated amounts, which are not-always what is shown by reports.  Eg a commodity directive may limit the-display precision, but this will not affect balance assertions.  Balance-assertion failure messages show exact amounts.---File: hledger.info,  Node: Posting comments,  Next: Tags,  Prev: Balance assertions,  Up: Journal--9.15 Posting comments-=====================--Text following ';', at the end of a posting line, and/or on indented-lines immediately below it, form comments for that posting.  They are-reproduced by 'print' but otherwise ignored, except they may contain-tags, which are not ignored.--2012-01-01-    expenses   1  ; a comment for posting 1-    assets-    ; a comment for posting 2-    ; a second comment line for posting 2---File: hledger.info,  Node: Tags,  Next: Directives,  Prev: Posting comments,  Up: Journal--9.16 Tags-=========--Tags are a way to add extra labels or labelled data to transactions,-postings, or accounts, which you can then search or pivot on.--   They are written as a word (optionally hyphenated) immediately-followed by a full colon, in a transaction or posting or account-directive's comment.  (This is an exception to the usual rule that-things in comments are ignored.)  Eg, here four different tags are-recorded: one on the checking account, two on the transaction, and one-on the expenses posting:--account assets:checking         ; accounttag:--2017/1/16 bought groceries      ; transactiontag-1:-    ; transactiontag-2:-    assets:checking        $-1-    expenses:food           $1  ; postingtag:--   Postings also inherit tags from their transaction and their account.-And transactions also acquire tags from their postings (and postings'-accounts).  So in the example above, the expenses posting effectively-has all four tags (by inheriting from account and transaction), and the-transaction also has all four tags (by acquiring from the expenses-posting).--   You can list tag names with 'hledger tags [NAMEREGEX]', or match by-tag name with a 'tag:NAMEREGEX' query.--* Menu:--* Tag values::---File: hledger.info,  Node: Tag values,  Up: Tags--9.16.1 Tag values--------------------Tags can have a value, which is any text after the colon up until a-comma or end of line (with surrounding whitespace removed).  Note this-means that hledger tag values can not contain commas.  Eg in the-following posting, the three tags' values are "value 1", "value 2", and-"" (empty) respectively:--    expenses:food   $10    ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz--   Note that tags can be repeated, and are additive rather than-overriding: when the same tag name is seen again with a new value, the-new name:value pair is added to the tags.  (It is not possible to-override a tag's value or remove a tag.)--   You can list a tag's values with 'hledger tags TAGNAME --values', or-match by tag value with a 'tag:NAMEREGEX=VALUEREGEX' query.---File: hledger.info,  Node: Directives,  Next: account directive,  Prev: Tags,  Up: Journal--9.17 Directives-===============--Besides transactions, there is something else you can put in a 'journal'-file: directives.  These are declarations, beginning with a keyword,-that modify hledger's behaviour.  Some directives can have more specific-subdirectives, indented below them.  hledger's directives are similar to-Ledger's in many cases, but there are also many differences.  Directives-are not required, but can be useful.  Here are the main directives:--purpose                                   directive----------------------------------------------------------------------------*READING DATA:*-Rewrite account names                     'alias'-Comment out sections of the file          'comment'-Declare file's decimal mark, to help      'decimal-mark'-parse amounts accurately-Include other data files                  'include'-*GENERATING DATA:*-Generate recurring transactions or        '~'-budget goals-Generate extra postings on existing       '='-transactions-*CHECKING FOR ERRORS:*-Define valid entities to provide more     'account', 'commodity',-error checking                            'payee', 'tag'-*REPORTING:*-Declare accounts' type and display        'account'-order-Declare commodity display styles          'commodity'-Declare market prices                     'P'--* Menu:--* Directives and multiple files::-* Directive effects::---File: hledger.info,  Node: Directives and multiple files,  Next: Directive effects,  Up: Directives--9.17.1 Directives and multiple files---------------------------------------Directives vary in their scope, ie which journal entries and which input-files they affect.  Most often, a directive will affect the following-entries and included files if any, until the end of the current file --and no further.  You might find this inconvenient!  For example, 'alias'-directives do not affect parent or sibling files.  But there are usually-workarounds; for example, put 'alias' directives in your top-most file,-before including other files.--   The restriction, though it may be annoying at first, is in a good-cause; it allows reports to be stable and deterministic, independent of-the order of input.  Without it, reports could show different numbers-depending on the order of -f options, or the positions of include-directives in your files.---File: hledger.info,  Node: Directive effects,  Prev: Directives and multiple files,  Up: Directives--9.17.2 Directive effects---------------------------Here are all hledger's directives, with their effects and scope-summarised - nine main directives, plus four others which we consider-non-essential:--directivewhat it does                                                   ends-                                                                        at-                                                                        file-                                                                        end?-----------------------------------------------------------------------------*'account'*Declares an account, for checking all entries in all files; andN-     its display order and type.  Subdirectives: any text, ignored.-*'alias'*Rewrites account names, in following entries until end of      Y-     current file or 'end aliases'.  Command line equivalent:-     '--alias'-*'comment'*Ignores part of the journal file, until end of current file orY-     'end comment'.-*'commodity'*Declares up to four things: 1.  a commodity symbol, for checkingN,Y,N,N-     all amounts in all files 2.  the decimal mark for parsing-     amounts of this commodity, in the following entries until end of-     current file (if there is no 'decimal-mark' directive) 3.  and-     the display style for amounts of this commodity 4.  which is-     also the precision to use for balanced-transaction checking in-     this commodity.  Takes precedence over 'D'.  Subdirectives:-     'format' (Ledger-compatible syntax).  Command line equivalent:-     '-c/--commodity-style'-*'decimal-mark'*Declares the decimal mark, for parsing amounts of all   Y-     commodities in following entries until next 'decimal-mark' or-     end of current file.  Included files can override.  Takes-     precedence over 'commodity' and 'D'.-*'include'*Includes entries and directives from another file, as if theyN-     were written inline.  Command line alternative: multiple-     '-f/--file'-*'payee'*Declares a payee name, for checking all entries in all files.  N-*'P'*Declares the market price of a commodity on some date, for value   N-     reports.-*'~'*Declares a periodic transaction rule that generates future         N-(tilde)transactions with '--forecast' and budget goals with 'balance-     --budget'.-Other-syntax:-*'applyPrepends a common parent account to all account names, in        Y-account'*following entries until end of current file or 'end apply-     account'.-*'D'*Sets a default commodity to use for no-symbol amounts;and, if      Y,Y,N,N-     there is no 'commodity' directive for this commodity: its-     decimal mark, balancing precision, and display style, as above.-*'Y'*Sets a default year to use for any yearless dates, in following    Y-     entries until end of current file.-*'='*Declares an auto posting rule that generates extra postings on     partly-(equals)matched transactions with '--auto', in current, parent, and-     child files (but not sibling files, see #1212).-*OtherOther directives from Ledger's file format are accepted but-Ledgerignored.-directives*---File: hledger.info,  Node: account directive,  Next: alias directive,  Prev: Directives,  Up: Journal--9.18 'account' directive-========================--'account' directives can be used to declare accounts (ie, the places-that amounts are transferred from and to).  Though not required, these-declarations can provide several benefits:--   * They can document your intended chart of accounts, providing a-     reference.-   * In strict mode, they restrict which accounts may be posted to by-     transactions, which helps detect typos.-   * They control account display order in reports, allowing-     non-alphabetic sorting (eg Revenues to appear above Expenses).-   * They help with account name completion (in hledger add,-     hledger-web, hledger-iadd, ledger-mode, etc.)-   * They can store additional account information as comments, or as-     tags which can be used to filter or pivot reports.-   * They can help hledger know your accounts' types (asset, liability,-     equity, revenue, expense), affecting reports like balancesheet and-     incomestatement.--   They are written as the word 'account' followed by a hledger-style-account name, eg:--account assets:bank:checking--   Note, however, that accounts declared in account directives are not-allowed to have surrounding brackets and parentheses, unlike accounts-used in postings.  So the following journal will not parse:--account (assets:bank:checking)--* Menu:--* Account comments::-* Account subdirectives::-* Account error checking::-* Account display order::-* Account types::---File: hledger.info,  Node: Account comments,  Next: Account subdirectives,  Up: account directive--9.18.1 Account comments--------------------------Text following *two or more spaces* and ';' at the end of an account-directive line, and/or following ';' on indented lines immediately below-it, form comments for that account.  They are ignored except they may-contain tags, which are not ignored.--   The two-space requirement for same-line account comments is because-';' is allowed in account names.--account assets:bank:checking    ; same-line comment, at least 2 spaces before the semicolon-  ; next-line comment-  ; some tags - type:A, acctnum:12345---File: hledger.info,  Node: Account subdirectives,  Next: Account error checking,  Prev: Account comments,  Up: account directive--9.18.2 Account subdirectives-------------------------------Ledger-style indented subdirectives are also accepted, but currently-ignored:--account assets:bank:checking-  format subdirective is ignored---File: hledger.info,  Node: Account error checking,  Next: Account display order,  Prev: Account subdirectives,  Up: account directive--9.18.3 Account error checking--------------------------------By default, accounts need not be declared; they come into existence when-a posting references them.  This is convenient, but it means hledger-can't warn you when you mis-spell an account name in the journal.-Usually you'll find that error later, as an extra account in balance-reports, or an incorrect balance when reconciling.--   In strict mode, enabled with the '-s'/'--strict' flag, hledger will-report an error if any transaction uses an account name that has not-been declared by an account directive.  Some notes:--   * The declaration is case-sensitive; transactions must use the-     correct account name capitalisation.-   * The account directive's scope is "whole file and below" (see-     directives).  This means it affects all of the current file, and-     any files it includes, but not parent or sibling files.  The-     position of account directives within the file does not matter,-     though it's usual to put them at the top.-   * Accounts can only be declared in 'journal' files, but will affect-     included files of all types.-   * It's currently not possible to declare "all possible subaccounts"-     with a wildcard; every account posted to must be declared.---File: hledger.info,  Node: Account display order,  Next: Account types,  Prev: Account error checking,  Up: account directive--9.18.4 Account display order-------------------------------The order in which account directives are written influences the order-in which accounts appear in reports, hledger-ui, hledger-web etc.  By-default accounts appear in alphabetical order, but if you add these-account directives to the journal file:--account assets-account liabilities-account equity-account revenues-account expenses--   those accounts will be displayed in declaration order:--$ hledger accounts -1-assets-liabilities-equity-revenues-expenses--   Any undeclared accounts are displayed last, in alphabetical order.--   Sorting is done at each level of the account tree, within each group-of sibling accounts under the same parent.  And currently, this-directive:--account other:zoo--   would influence the position of 'zoo' among 'other''s subaccounts,-but not the position of 'other' among the top-level accounts.  This-means:--   * you will sometimes declare parent accounts (eg 'account other'-     above) that you don't intend to post to, just to customize their-     display order-   * sibling accounts stay together (you couldn't display 'x:y' in-     between 'a:b' and 'a:c').---File: hledger.info,  Node: Account types,  Prev: Account display order,  Up: account directive--9.18.5 Account types-----------------------hledger knows that accounts come in several types: assets, liabilities,-expenses and so on.  This enables easy reports like balancesheet and-incomestatement, and filtering by account type with the 'type:' query.--   As a convenience, hledger will detect these account types-automatically if you are using common english-language top-level account-names (described below).  But generally we recommend you declare types-explicitly, by adding a 'type:' tag to your top-level account-directives.  Subaccounts will inherit the type of their parent.  The-tag's value should be one of the five main account types:--   * 'A' or 'Asset' (things you own)-   * 'L' or 'Liability' (things you owe)-   * 'E' or 'Equity' (investment/ownership; balanced counterpart of-     assets & liabilities)-   * 'R' or 'Revenue' (what you received money from, AKA income;-     technically part of Equity)-   * 'X' or 'Expense' (what you spend money on; technically part of-     Equity)--   or, it can be (these are used less often):--   * 'C' or 'Cash' (a subtype of Asset, indicating liquid assets for the-     cashflow report)-   * 'V' or 'Conversion' (a subtype of Equity, for conversions (see Cost-     reporting).)--   Here is a typical set of account type declarations:--account assets             ; type: A-account liabilities        ; type: L-account equity             ; type: E-account revenues           ; type: R-account expenses           ; type: X--account assets:bank        ; type: C-account assets:cash        ; type: C--account equity:conversion  ; type: V--   Here are some tips for working with account types.--   * The rules for inferring types from account names are as follows.-     These are just a convenience that sometimes help new users get-     going; if they don't work for you, just ignore them and declare-     your account types.  See also Regular expressions.--     If account's name contains this (CI) regular expression:            | its type is:-     --------------------------------------------------------------------|--------------     ^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|current)(:|$) | Cash-     ^assets?(:|$)                                                       | Asset-     ^(debts?|liabilit(y|ies))(:|$)                                      | Liability-     ^equity:(trad(e|ing)|conversion)s?(:|$)                             | Conversion-     ^equity(:|$)                                                        | Equity-     ^(income|revenue)s?(:|$)                                            | Revenue-     ^expenses?(:|$)                                                     | Expense--   * If you declare any account types, it's a good idea to declare an-     account for all of the account types, because a mixture of declared-     and name-inferred types can disrupt certain reports.--   * Certain uses of account aliases can disrupt account types.  See-     Rewriting accounts > Aliases and account types.--   * As mentioned above, subaccounts will inherit a type from their-     parent account.  More precisely, an account's type is decided by-     the first of these that exists:--       1. A 'type:' declaration for this account.-       2. A 'type:' declaration in the parent accounts above it,-          preferring the nearest.-       3. An account type inferred from this account's name.-       4. An account type inferred from a parent account's name,-          preferring the nearest parent.-       5. Otherwise, it will have no type.--   * For troubleshooting, you can list accounts and their types with:--     $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES]---File: hledger.info,  Node: alias directive,  Next: commodity directive,  Prev: account directive,  Up: Journal--9.19 'alias' directive-======================--You can define account alias rules which rewrite your account names, or-parts of them, before generating reports.  This can be useful for:--   * expanding shorthand account names to their full form, allowing-     easier data entry and a less verbose journal-   * adapting old journals to your current chart of accounts-   * experimenting with new account organisations, like a new hierarchy-   * combining two accounts into one, eg to see their sum or difference-     on one line-   * customising reports--   Account aliases also rewrite account names in account directives.-They do not affect account names being entered via hledger add or-hledger-web.--   Account aliases are very powerful.  They are generally easy to use-correctly, but you can also generate invalid account names with them;-more on this below.--   See also Rewrite account names.--* Menu:--* Basic aliases::-* Regex aliases::-* Combining aliases::-* Aliases and multiple files::-* end aliases directive::-* Aliases can generate bad account names::-* Aliases and account types::---File: hledger.info,  Node: Basic aliases,  Next: Regex aliases,  Up: alias directive--9.19.1 Basic aliases-----------------------To set an account alias, use the 'alias' directive in your journal file.-This affects all subsequent journal entries in the current file or its-included files (but note: not sibling or parent files).  The spaces-around the = are optional:--alias OLD = NEW--   Or, you can use the '--alias 'OLD=NEW'' option on the command line.-This affects all entries.  It's useful for trying out aliases-interactively.--   OLD and NEW are case sensitive full account names.  hledger will-replace any occurrence of the old account name with the new one.-Subaccounts are also affected.  Eg:--alias checking = assets:bank:wells fargo:checking-; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"---File: hledger.info,  Node: Regex aliases,  Next: Combining aliases,  Prev: Basic aliases,  Up: alias directive--9.19.2 Regex aliases-----------------------There is also a more powerful variant that uses a regular expression,-indicated by wrapping the pattern in forward slashes.  (This is the only-place where hledger requires forward slashes around a regular-expression.)--   Eg:--alias /REGEX/ = REPLACEMENT--   or:--$ hledger --alias '/REGEX/=REPLACEMENT' ...--   Any part of an account name matched by REGEX will be replaced by-REPLACEMENT. REGEX is case-insensitive as usual.--   If you need to match a forward slash, escape it with a backslash, eg-'/\/=:'.--   If REGEX contains parenthesised match groups, these can be referenced-by the usual backslash and number in REPLACEMENT:--alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3-; rewrites "assets:bank:wells fargo:checking" to  "assets:wells fargo checking"--   REPLACEMENT continues to the end of line (or on command line, to end-of option argument), so it can contain trailing whitespace.---File: hledger.info,  Node: Combining aliases,  Next: Aliases and multiple files,  Prev: Regex aliases,  Up: alias directive--9.19.3 Combining aliases---------------------------You can define as many aliases as you like, using journal directives-and/or command line options.--   Recursive aliases - where an account name is rewritten by one alias,-then by another alias, and so on - are allowed.  Each alias sees the-effect of previously applied aliases.--   In such cases it can be important to understand which aliases will be-applied and in which order.  For (each account name in) each journal-entry, we apply:--  1. 'alias' directives preceding the journal entry, most recently-     parsed first (ie, reading upward from the journal entry, bottom to-     top)-  2. '--alias' options, in the order they appeared on the command line-     (left to right).--   In other words, for (an account name in) a given journal entry:--   * the nearest alias declaration before/above the entry is applied-     first-   * the next alias before/above that will be be applied next, and so on-   * aliases defined after/below the entry do not affect it.--   This gives nearby aliases precedence over distant ones, and helps-provide semantic stability - aliases will keep working the same way-independent of which files are being read and in which order.--   In case of trouble, adding '--debug=6' to the command line will show-which aliases are being applied when.---File: hledger.info,  Node: Aliases and multiple files,  Next: end aliases directive,  Prev: Combining aliases,  Up: alias directive--9.19.4 Aliases and multiple files------------------------------------As explained at Directives and multiple files, 'alias' directives do not-affect parent or sibling files.  Eg in this command,--hledger -f a.aliases -f b.journal--   account aliases defined in a.aliases will not affect b.journal.-Including the aliases doesn't work either:--include a.aliases--2023-01-01  ; not affected by a.aliases-  foo  1-  bar--   This means that account aliases should usually be declared at the-start of your top-most file, like this:--alias foo=Foo-alias bar=Bar--2023-01-01  ; affected by aliases above-  foo  1-  bar--include c.journal  ; also affected---File: hledger.info,  Node: end aliases directive,  Next: Aliases can generate bad account names,  Prev: Aliases and multiple files,  Up: alias directive--9.19.5 'end aliases' directive---------------------------------You can clear (forget) all currently defined aliases (seen in the-journal so far, or defined on the command line) with this directive:--end aliases---File: hledger.info,  Node: Aliases can generate bad account names,  Next: Aliases and account types,  Prev: end aliases directive,  Up: alias directive--9.19.6 Aliases can generate bad account names------------------------------------------------Be aware that account aliases can produce malformed account names, which-could cause confusing reports or invalid 'print' output.  For example,-you could erase all account names:--2021-01-01-  a:aa     1-  b--$ hledger print --alias '/.*/='-2021-01-01-                   1--   The above 'print' output is not a valid journal.  Or you could insert-an illegal double space, causing 'print' output that would give a-different journal when reparsed:--2021-01-01-  old    1-  other--$ hledger print --alias old="new  USD" | hledger -f- print-2021-01-01-    new             USD 1-    other---File: hledger.info,  Node: Aliases and account types,  Prev: Aliases can generate bad account names,  Up: alias directive--9.19.7 Aliases and account types-----------------------------------If an account with a type declaration (see Declaring accounts > Account-types) is renamed by an alias, normally the account type remains in-effect.--   However, renaming in a way that reshapes the account tree (eg-renaming parent accounts but not their children, or vice versa) could-prevent child accounts from inheriting the account type of their-parents.--   Secondly, if an account's type is being inferred from its name,-renaming it by an alias could prevent or alter that.--   If you are using account aliases and the 'type:' query is not-matching accounts as you expect, try troubleshooting with the accounts-command, eg something like:--$ hledger accounts --alias assets=bassetts type:a---File: hledger.info,  Node: commodity directive,  Next: decimal-mark directive,  Prev: alias directive,  Up: Journal--9.20 'commodity' directive-==========================--The 'commodity' directive performs several functions:--  1. It declares which commodity symbols may be used in the journal,-     enabling useful error checking with strict mode or the check-     command.  (See Commodity error checking below.)--  2. It declares the precision with which this commodity's amounts-     should be compared when checking for balanced transactions.--  3. It declares how this commodity's amounts should be displayed, eg-     their symbol placement, digit group mark if any, digit group sizes,-     decimal mark (period or comma), and the number of decimal places.-     (See Commodity display style above.)--  4. It sets which decimal mark (period or comma) to expect when parsing-     subsequent amounts in this commodity (if there is no 'decimal-mark'-     directive in effect.  See Decimal marks, digit group marks above.-     For related dev discussion, see #793.)--   Declaring commodities solves several common parsing/display problems,-so we recommend it.  Generally you should put 'commodity' directives at-the top of your journal file (because function 4 is position-sensitive).--* Menu:--* Commodity directive syntax::-* Commodity error checking::---File: hledger.info,  Node: Commodity directive syntax,  Next: Commodity error checking,  Up: commodity directive--9.20.1 Commodity directive syntax------------------------------------A commodity directive is normally the word 'commodity' followed by a-sample amount (and optionally a comment).  Only the amount's symbol and-format is significant.  Eg:--commodity $1000.00-commodity 1.000,00 EUR-commodity 1 000 000.0000   ; the no-symbol commodity--   A commodity directive's sample amount must always include a period or-comma decimal mark (this rule helps disambiguate decimal marks and digit-group marks).  If you don't want to show any decimal digits, write the-decimal mark at the end:--commodity 1000. AAAA       ; show AAAA with no decimals--   Commodity symbols containing spaces, numbers, or punctuation must be-enclosed in double quotes, as usual:--commodity 1.0000 "AAAA 2023"--   Commodity directives normally include a sample amount, but can-declare only a symbol (ie, just function 1 above):--commodity $-commodity INR-commodity "AAAA 2023"-commodity ""               ; the no-symbol commodity--   Commodity directives may also be written with an indented 'format'-subdirective, as in Ledger.  The symbol is repeated and must be the same-in both places.  Other subdirectives are currently ignored:--; display indian rupees with currency name on the left,-; thousands, lakhs and crores comma-separated,-; period as decimal point, and two decimal places.-commodity INR-  format INR 1,00,00,000.00-  an unsupported subdirective  ; ignored by hledger---File: hledger.info,  Node: Commodity error checking,  Prev: Commodity directive syntax,  Up: commodity directive--9.20.2 Commodity error checking----------------------------------In strict mode ('-s'/'--strict') (or when you run 'hledger check-commodities'), hledger will report an error if an undeclared commodity-symbol is used.  (With one exception: zero amounts are always allowed to-have no commodity symbol.)  It works like account error checking-(described above).---File: hledger.info,  Node: decimal-mark directive,  Next: include directive,  Prev: commodity directive,  Up: Journal--9.21 'decimal-mark' directive-=============================--You can use a 'decimal-mark' directive - usually one per file, at the-top of the file - to declare which character represents a decimal mark-when parsing amounts in this file.  It can look like--decimal-mark .--   or--decimal-mark ,--   This prevents any ambiguity when parsing numbers in the file, so we-recommend it, especially if the file contains digit group marks (eg-thousands separators).---File: hledger.info,  Node: include directive,  Next: P directive,  Prev: decimal-mark directive,  Up: Journal--9.22 'include' directive-========================--You can pull in the content of additional files by writing an include-directive, like this:--include FILEPATH--   Only journal files can include, and only journal, timeclock or-timedot files can be included (not CSV files, currently).--   If the file path does not begin with a slash, it is relative to the-current file's folder.--   A tilde means home directory, eg: 'include ~/main.journal'.--   The path may contain glob patterns to match multiple files, eg:-'include *.journal'.--   There is limited support for recursive wildcards: '**/' (the slash is-required) matches 0 or more subdirectories.  It's not super convenient-since you have to avoid include cycles and including directories, but-this can be done, eg: 'include */**/*.journal'.--   The path may also be prefixed to force a specific file format,-overriding the file extension (as described in Data formats): 'include-timedot:~/notes/2023*.md'.---File: hledger.info,  Node: P directive,  Next: payee directive,  Prev: include directive,  Up: Journal--9.23 'P' directive-==================--The 'P' directive declares a market price, which is a conversion rate-between two commodities on a certain date.  This allows value reports to-convert amounts of one commodity to their value in another, on or after-that date.  These prices are often obtained from a stock exchange,-cryptocurrency exchange, the or foreign exchange market.--   The format is:--P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT--   DATE is a simple date, COMMODITY1SYMBOL is the symbol of the-commodity being priced, and COMMODITY2AMOUNT is the amount (symbol and-quantity) of commodity 2 that one unit of commodity 1 is worth on this-date.  Examples:--# one euro was worth $1.35 from 2009-01-01 onward:-P 2009-01-01 € $1.35--# and $1.40 from 2010-01-01 onward:-P 2010-01-01 € $1.40--   The '-V', '-X' and '--value' flags use these market prices to show-amount values in another commodity.  See Value reporting.---File: hledger.info,  Node: payee directive,  Next: tag directive,  Prev: P directive,  Up: Journal--9.24 'payee' directive-======================--'payee PAYEE NAME'--   This directive can be used to declare a limited set of payees which-may appear in transaction descriptions.  The "payees" check will report-an error if any transaction refers to a payee that has not been-declared.  Eg:--payee Whole Foods--   Any indented subdirectives are currently ignored.---File: hledger.info,  Node: tag directive,  Next: Periodic transactions,  Prev: payee directive,  Up: Journal--9.25 'tag' directive-====================--'tag TAGNAME'--   This directive can be used to declare a limited set of tag names-allowed in tags.  TAGNAME should be a valid tag name (no spaces).  Eg:--tag  item-id--   Any indented subdirectives are currently ignored.--   The "tags" check will report an error if any undeclared tag name is-used.  It is quite easy to accidentally create a tag through normal use-of colons in comments(#comments]; if you want to prevent this, you can-declare and check your tags .---File: hledger.info,  Node: Periodic transactions,  Next: Auto postings,  Prev: tag directive,  Up: Journal--9.26 Periodic transactions-==========================--The '~' directive declares recurring transactions.  Such directives-allow hledger to generate temporary future transactions (visible in-reports, not in the journal file) to help with forecasting or budgeting.--   Periodic transactions can be a little tricky, so before you use them,-read this whole section, or at least these tips:--  1. Two spaces accidentally added or omitted will cause you trouble --     read about this below.-  2. For troubleshooting, show the generated transactions with 'hledger-     print --forecast tag:generated' or 'hledger register --forecast-     tag:generated'.-  3. Forecasted transactions will begin only after the last-     non-forecasted transaction's date.-  4. Forecasted transactions will end 6 months from today, by default.-     See below for the exact start/end rules.-  5. period expressions can be tricky.  Their documentation needs-     improvement, but is worth studying.-  6. Some period expressions with a repeating interval must begin on a-     natural boundary of that interval.  Eg in 'weekly from DATE', DATE-     must be a monday.  '~ weekly from 2019/10/1' (a tuesday) will give-     an error.-  7. Other period expressions with an interval are automatically-     expanded to cover a whole number of that interval.  (This is done-     to improve reports, but it also affects periodic transactions.-     Yes, it's a bit inconsistent with the above.)  Eg: '~ every 10th-     day of month from 2023/01', which is equivalent to '~ every 10th-     day of month from 2023/01/01', will be adjusted to start on-     2019/12/10.--* Menu:--* Periodic rule syntax::-* Periodic rules and relative dates::-* Two spaces between period expression and description!::---File: hledger.info,  Node: Periodic rule syntax,  Next: Periodic rules and relative dates,  Up: Periodic transactions--9.26.1 Periodic rule syntax------------------------------A periodic transaction rule looks like a normal journal entry, with the-date replaced by a tilde ('~') followed by a period expression-(mnemonic: '~' looks like a recurring sine wave.):--# every first of month-~ monthly-    expenses:rent          $2000-    assets:bank:checking--# every 15th of month in 2023's first quarter:-~ monthly from 2023-04-15 to 2023-06-16-    expenses:utilities          $400-    assets:bank:checking--   The period expression is the same syntax used for specifying-multi-period reports, just interpreted differently; there, it specifies-report periods; here it specifies recurrence dates (the periods' start-dates).---File: hledger.info,  Node: Periodic rules and relative dates,  Next: Two spaces between period expression and description!,  Prev: Periodic rule syntax,  Up: Periodic transactions--9.26.2 Periodic rules and relative dates-------------------------------------------Partial or relative dates (like '12/31', '25', 'tomorrow', 'last week',-'next quarter') are usually not recommended in periodic rules, since the-results will change as time passes.  If used, they will be interpreted-relative to, in order of preference:--  1. the first day of the default year specified by a recent 'Y'-     directive-  2. or the date specified with '--today'-  3. or the date on which you are running the report.--   They will not be affected at all by report period or forecast period-dates.---File: hledger.info,  Node: Two spaces between period expression and description!,  Prev: Periodic rules and relative dates,  Up: Periodic transactions--9.26.3 Two spaces between period expression and description!---------------------------------------------------------------If the period expression is followed by a transaction description, these-must be separated by *two or more spaces*.  This helps hledger know-where the period expression ends, so that descriptions can not-accidentally alter their meaning, as in this example:--; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2023"-;               ||-;               vv-~ every 2 months  in 2023, we will review-    assets:bank:checking   $1500-    income:acme inc--   So,--   * Do write two spaces between your period expression and your-     transaction description, if any.-   * Don't accidentally write two spaces in the middle of your period-     expression.---File: hledger.info,  Node: Auto postings,  Next: Other syntax,  Prev: Periodic transactions,  Up: Journal--9.27 Auto postings-==================--The '=' directive declares a rule for generating temporary extra-postings on transactions.  Wherever the rule matches an existing-posting, it can add one or more companion postings below that one,-optionally influenced by the matched posting's amount.  This can be-useful for generating tax postings with a standard percentage, for-example.--   Note that depending on generated data is not ideal for financial-records (it's less portable, less future-proof, less auditable by-others, and less robust, since other features like balance assertions-will depend on using or not using '--auto').--   An auto posting rule looks a bit like a transaction:--= QUERY-    ACCOUNT  AMOUNT-    ...-    ACCOUNT  [AMOUNT]--   except the first line is an equals sign (mnemonic: '=' suggests-matching), followed by a query (which matches existing postings), and-each "posting" line describes a posting to be generated, and the posting-amounts can be:--   * a normal amount with a commodity symbol, eg '$2'.  This will be-     used as-is.-   * a number, eg '2'.  The commodity symbol (if any) from the matched-     posting will be added to this.-   * a numeric multiplier, eg '*2' (a star followed by a number N). The-     matched posting's amount (and total price, if any) will be-     multiplied by N.-   * a multiplier with a commodity symbol, eg '*$2' (a star, number N,-     and symbol S). The matched posting's amount will be multiplied by-     N, and its commodity symbol will be replaced with S.--   Any query term containing spaces must be enclosed in single or double-quotes, as on the command line.  Eg, note the quotes around the second-query term below:--= expenses:groceries 'expenses:dining out'-    (budget:funds:dining out)                 *-1--   Some examples:--; every time I buy food, schedule a dollar donation-= expenses:food-    (liabilities:charity)   $-1--; when I buy a gift, also deduct that amount from a budget envelope subaccount-= expenses:gifts-    assets:checking:gifts  *-1-    assets:checking         *1--2017/12/1-  expenses:food    $10-  assets:checking--2017/12/14-  expenses:gifts   $20-  assets:checking--$ hledger print --auto-2017-12-01-    expenses:food              $10-    assets:checking-    (liabilities:charity)      $-1--2017-12-14-    expenses:gifts             $20-    assets:checking-    assets:checking:gifts     -$20-    assets:checking            $20--* Menu:--* Auto postings and multiple files::---File: hledger.info,  Node: Auto postings and multiple files,  Up: Auto postings--9.27.1 Auto postings and multiple files------------------------------------------An auto posting rule can affect any transaction in the current file, or-in any parent file or child file.  Note, currently it will not affect-sibling files (when multiple '-f'/'--file' are used - see #1212).--* Menu:--* Auto postings and dates::-* Auto postings and transaction balancing / inferred amounts / balance assertions::-* Auto posting tags::-* Auto postings on forecast transactions only::---File: hledger.info,  Node: Auto postings and dates,  Next: Auto postings and transaction balancing / inferred amounts / balance assertions,  Up: Auto postings and multiple files--9.27.1.1 Auto postings and dates-................................--A posting date (or secondary date) in the matched posting, or (taking-precedence) a posting date in the auto posting rule itself, will also be-used in the generated posting.---File: hledger.info,  Node: Auto postings and transaction balancing / inferred amounts / balance assertions,  Next: Auto posting tags,  Prev: Auto postings and dates,  Up: Auto postings and multiple files--9.27.1.2 Auto postings and transaction balancing / inferred-...........................................................--amounts / balance assertions Currently, auto postings are added:--   * after missing amounts are inferred, and transactions are checked-     for balancedness,-   * but before balance assertions are checked.--   Note this means that journal entries must be balanced both before and-after auto postings are added.  This changed in hledger 1.12+; see #893-for background.--   This also means that you cannot have more than one auto-posting with-a missing amount applied to a given transaction, as it will be unable to-infer amounts.---File: hledger.info,  Node: Auto posting tags,  Next: Auto postings on forecast transactions only,  Prev: Auto postings and transaction balancing / inferred amounts / balance assertions,  Up: Auto postings and multiple files--9.27.1.3 Auto posting tags-..........................--Automated postings will have some extra tags:--   * 'generated-posting:= QUERY' - shows this was generated by an auto-     posting rule, and the query-   * '_generated-posting:= QUERY' - a hidden tag, which does not appear-     in hledger's output.  This can be used to match postings generated-     "just now", rather than generated in the past and saved to the-     journal.--   Also, any transaction that has been changed by auto posting rules-will have these tags added:--   * 'modified:' - this transaction was modified-   * '_modified:' - a hidden tag not appearing in the comment; this-     transaction was modified "just now".---File: hledger.info,  Node: Auto postings on forecast transactions only,  Prev: Auto posting tags,  Up: Auto postings and multiple files--9.27.1.4 Auto postings on forecast transactions only-....................................................--Tip: you can can make auto postings that will apply to forecast-transactions but not recorded transactions, by adding-'tag:_generated-transaction' to their QUERY. This can be useful when-generating new journal entries to be saved in the journal.---File: hledger.info,  Node: Other syntax,  Prev: Auto postings,  Up: Journal--9.28 Other syntax-=================--hledger journal format supports quite a few other features, mainly to-make interoperating with or converting from Ledger easier.  Note some of-the features below are powerful and can be useful in special cases, but-in general, features in this section are considered less important or-even not recommended for most users.  Downsides are mentioned to help-you decide if you want to use them.--* Menu:--* Balance assignments::-* Bracketed posting dates::-* D directive::-* apply account directive::-* Y directive::-* Secondary dates::-* Star comments::-* Valuation expressions::-* Virtual postings::-* Other Ledger directives::---File: hledger.info,  Node: Balance assignments,  Next: Bracketed posting dates,  Up: Other syntax--9.28.1 Balance assignments-----------------------------Ledger-style balance assignments are also supported.  These are like-balance assertions, but with no posting amount on the left side of the-equals sign; instead it is calculated automatically so as to satisfy the-assertion.  This can be a convenience during data entry, eg when setting-opening balances:--; starting a new journal, set asset account balances-2016/1/1 opening balances-  assets:checking            = $409.32-  assets:savings             = $735.24-  assets:cash                 = $42-  equity:opening balances--   or when adjusting a balance to reality:--; no cash left; update balance, record any untracked spending as a generic expense-2016/1/15-  assets:cash    = $0-  expenses:misc--   The calculated amount depends on the account's balance in the-commodity at that point (which depends on the previously-dated postings-of the commodity to that account since the last balance assertion or-assignment).--   Downsides: using balance assignments makes your journal less-explicit; to know the exact amount posted, you have to run hledger or do-the calculations yourself, instead of just reading it.  Also balance-assignments' forcing of balances can hide errors.  These things make-your financial data less portable, less future-proof, and less-trustworthy in an audit.--* Menu:--* Balance assignments and prices::-* Balance assignments and multiple files::---File: hledger.info,  Node: Balance assignments and prices,  Next: Balance assignments and multiple files,  Up: Balance assignments--9.28.1.1 Balance assignments and prices-.......................................--A cost in a balance assignment will cause the calculated amount to have-that price attached:--2019/1/1-  (a)             = $1 @ €2--$ hledger print --explicit-2019-01-01-    (a)         $1 @ €2 = $1 @ €2---File: hledger.info,  Node: Balance assignments and multiple files,  Prev: Balance assignments and prices,  Up: Balance assignments--9.28.1.2 Balance assignments and multiple files-...............................................--Balance assignments handle multiple files like balance assertions.  They-see balance from other files previously included from the current file,-but not from previous sibling or parent files.---File: hledger.info,  Node: Bracketed posting dates,  Next: D directive,  Prev: Balance assignments,  Up: Other syntax--9.28.2 Bracketed posting dates---------------------------------For setting posting dates and secondary posting dates, Ledger's-bracketed date syntax is also supported: '[DATE]', '[DATE=DATE2]' or-'[=DATE2]' in posting comments.  hledger will attempt to parse any-square-bracketed sequence of the '0123456789/-.=' characters in this-way.  With this syntax, DATE infers its year from the transaction and-DATE2 infers its year from DATE.--   Downsides: another syntax to learn, redundant with hledger's-'date:'/'date2:' tags, and confusingly similar to Ledger's lot date-syntax.---File: hledger.info,  Node: D directive,  Next: apply account directive,  Prev: Bracketed posting dates,  Up: Other syntax--9.28.3 'D' directive-----------------------'D AMOUNT'--   This directive sets a default commodity, to be used for any-subsequent commodityless amounts (ie, plain numbers) seen while parsing-the journal.  This effect lasts until the next 'D' directive, or the end-of the journal.--   For compatibility/historical reasons, 'D' also acts like a-'commodity' directive (setting the commodity's decimal mark for parsing-and display style for output).  So its argument is not just a commodity-symbol, but a full amount demonstrating the style.  The amount must-include a decimal mark (either period or comma).  Eg:--; commodity-less amounts should be treated as dollars-; (and displayed with the dollar sign on the left, thousands separators and two decimal places)-D $1,000.00--1/1-  a     5  ; <- commodity-less amount, parsed as $5 and displayed as $5.00-  b--   Interactions with other directives:--   For setting a commodity's display style, a 'commodity' directive has-highest priority, then a 'D' directive.--   For detecting a commodity's decimal mark during parsing,-'decimal-mark' has highest priority, then 'commodity', then 'D'.--   For checking commodity symbols with the check command, a 'commodity'-directive is required ('hledger check commodities' ignores 'D'-directives).--   Downsides: omitting commodity symbols makes your financial data less-explicit, less portable, and less trustworthy in an audit.  It is-usually an unsustainable shortcut; sooner or later you will want to-track multiple commodities.  D is overloaded with functions redundant-with 'commodity' and 'decimal-mark'.  And it works differently from-Ledger's 'D'.---File: hledger.info,  Node: apply account directive,  Next: Y directive,  Prev: D directive,  Up: Other syntax--9.28.4 'apply account' directive-----------------------------------This directive sets a default parent account, which will be prepended to-all accounts in following entries, until an 'end apply account'-directive or end of current file.  Eg:--apply account home--2010/1/1-    food    $10-    cash--end apply account--   is equivalent to:--2010/01/01-    home:food           $10-    home:cash          $-10--   'account' directives are also affected, and so is any 'include'd-content.--   Account names entered via hledger add or hledger-web are not-affected.--   Account aliases, if any, are applied after the parent account is-prepended.--   Downsides: this can make your financial data less explicit, less-portable, and less trustworthy in an audit.---File: hledger.info,  Node: Y directive,  Next: Secondary dates,  Prev: apply account directive,  Up: Other syntax--9.28.5 'Y' directive-----------------------'Y YEAR'--   or (deprecated backward-compatible forms):--   'year YEAR' 'apply year YEAR'--   The space is optional.  This sets a default year to be used for-subsequent dates which don't specify a year.  Eg:--Y2009  ; set default year to 2009--12/15  ; equivalent to 2009/12/15-  expenses  1-  assets--year 2010  ; change default year to 2010--2009/1/30  ; specifies the year, not affected-  expenses  1-  assets--1/31   ; equivalent to 2010/1/31-  expenses  1-  assets--   Downsides: omitting the year (from primary transaction dates, at-least) makes your financial data less explicit, less portable, and less-trustworthy in an audit.  Such dates can get separated from their-corresponding Y directive, eg when evaluating a region of the journal in-your editor.  A missing Y directive makes reports dependent on today's-date.---File: hledger.info,  Node: Secondary dates,  Next: Star comments,  Prev: Y directive,  Up: Other syntax--9.28.6 Secondary dates-------------------------A secondary date is written after the primary date, following an equals-sign.  If the year is omitted, the primary date's year is assumed.  When-running reports, the primary (left) date is used by default, but with-the '--date2' flag (or '--aux-date' or '--effective'), the secondary-(right) date will be used instead.--   The meaning of secondary dates is up to you, but it's best to follow-a consistent rule.  Eg "primary = the bank's clearing date, secondary =-date the transaction was initiated, if different".--   Downsides: makes your financial data more complicated, less portable,-and less trustworthy in an audit.  Keeping the meaning of the two dates-consistent requires discipline, and you have to remember which reporting-mode is appropriate for a given report.  Posting dates are simpler and-better.---File: hledger.info,  Node: Star comments,  Next: Valuation expressions,  Prev: Secondary dates,  Up: Other syntax--9.28.7 Star comments-----------------------Lines beginning with '*' (star/asterisk) are also comment lines.  This-feature allows Emacs users to insert org headings in their journal,-allowing them to fold/unfold/navigate it like an outline when viewed-with org mode.--   Downsides: another, unconventional comment syntax to learn.-Decreases your journal's portability.  And switching to Emacs org mode-just for folding/unfolding meant losing the benefits of ledger mode;-nowadays you can add outshine mode to ledger mode to get folding without-losing ledger mode's features.---File: hledger.info,  Node: Valuation expressions,  Next: Virtual postings,  Prev: Star comments,  Up: Other syntax--9.28.8 Valuation expressions-------------------------------Ledger allows a valuation function or value to be written in double-parentheses after an amount.  hledger ignores these.---File: hledger.info,  Node: Virtual postings,  Next: Other Ledger directives,  Prev: Valuation expressions,  Up: Other syntax--9.28.9 Virtual postings--------------------------A posting with parentheses around the account name ('(some:account)') is-called a _unbalanced virtual posting_.  Such postings do not participate-in transaction balancing.  (And if you write them without an amount, a-zero amount is always inferred.)  These can occasionally be convenient-for special circumstances, but they violate double entry bookkeeping and-make your data less portable across applications, so many people avoid-using them at all.--   A posting with brackets around the account name ('[some:account]') is-called a _balanced virtual posting_.  The balanced virtual postings in a-transaction must add up to zero, just like ordinary postings, but-separately from them.  These are not part of double entry bookkeeping-either, but they are at least balanced.  An example:--2022-01-01 buy food with cash, update budget envelope subaccounts, & something else-  assets:cash                    $-10  ; <- these balance each other-  expenses:food                    $7  ; <--  expenses:food                    $3  ; <--  [assets:checking:budget:food]  $-10  ;   <- and these balance each other-  [assets:checking:available]     $10  ;   <--  (something:else)                 $5  ;     <- this is not required to balance--   Ordinary postings, whose account names are neither parenthesised nor-bracketed, are called _real postings_.  You can exclude virtual postings-from reports with the '-R/--real' flag or a 'real:1' query.---File: hledger.info,  Node: Other Ledger directives,  Prev: Virtual postings,  Up: Other syntax--9.28.10 Other Ledger directives----------------------------------These other Ledger directives are currently accepted but ignored.  This-allows hledger to read more Ledger files, but be aware that hledger's-reports may differ from Ledger's if you use these.--apply fixed COMM AMT-apply tag   TAG-assert      EXPR-bucket / A  ACCT-capture     ACCT REGEX-check       EXPR-define      VAR=EXPR-end apply fixed-end apply tag-end apply year-end tag-eval / expr EXPR-python-  PYTHONCODE-tag         NAME-value       EXPR---command-line-flags--   See also https://hledger.org/ledger.html for a detailed-hledger/Ledger syntax comparison.---File: hledger.info,  Node: CSV,  Next: Timeclock,  Prev: Journal,  Up: Top--10 CSV-******--hledger can read CSV files (Character Separated Value - usually comma,-semicolon, or tab) containing dated records, automatically converting-each record into a transaction.--   (To learn about _writing_ CSV, see CSV output.)--   For best error messages when reading CSV/TSV/SSV files, make sure-they have a corresponding '.csv', '.tsv' or '.ssv' file extension or use-a hledger file prefix (see File Extension below).--   Each CSV file must be described by a corresponding _rules file_.-This contains rules describing the CSV data (header line, fields layout,-date format etc.), how to construct hledger transactions from it, and-how to categorise transactions based on description or other attributes.--   By default hledger looks for a rules file named like the CSV file-with an extra '.rules' extension, in the same directory.  Eg when asked-to read 'foo/FILE.csv', hledger looks for 'foo/FILE.csv.rules'.  You can-specify a different rules file with the '--rules-file' option.  If no-rules file is found, hledger will create a sample rules file, which-you'll need to adjust.--   At minimum, the rules file must identify the date and amount fields,-and often it also specifies the date format and how many header lines-there are.  Here's a simple CSV file and a rules file for it:--Date, Description, Id, Amount-12/11/2019, Foo, 123, 10.23--# basic.csv.rules-skip         1-fields       date, description, , amount-date-format  %d/%m/%Y--$ hledger print -f basic.csv-2019-11-12 Foo-    expenses:unknown           10.23-    income:unknown            -10.23--   There's an introductory Importing CSV data tutorial on hledger.org,-and more CSV rules examples below, and a larger collection at-https://github.com/simonmichael/hledger/tree/master/examples/csv.--* Menu:--* CSV rules cheatsheet::-* source::-* separator::-* skip::-* date-format::-* timezone::-* newest-first::-* intra-day-reversed::-* decimal-mark::-* fields list::-* Field assignment::-* Field names::-* if block::-* Matchers::-* if table::-* balance-type::-* include::-* Working with CSV::-* CSV rules examples::---File: hledger.info,  Node: CSV rules cheatsheet,  Next: source,  Up: CSV--10.1 CSV rules cheatsheet-=========================--The following kinds of rule can appear in the rules file, in any order.-(Blank lines and lines beginning with '#' or ';' or '*' are ignored.)--*'source'*               optionally declare which file to read data-                         from-*'separator'*            declare the field separator, instead of-                         relying on file extension-*'skip'*                 skip one or more header lines at start of file-*'date-format'*          declare how to parse CSV dates/date-times-*'timezone'*             declare the time zone of ambiguous CSV-                         date-times-*'newest-first'*         improve txn order when: there are multiple-                         records, newest first, all with the same date-*'intra-day-reversed'*   improve txn order when: same-day txns are in-                         opposite order to the overall file-*'decimal-mark'*         declare the decimal mark used in CSV amounts,-                         when ambiguous-*'fields' list*          name CSV fields for easy reference, and-                         optionally assign their values to hledger-                         fields-*Field assignment*       assign a CSV value or interpolated text value-                         to a hledger field-*'if' block*             conditionally assign values to hledger fields,-                         or 'skip' a record or 'end' (skip rest of-                         file)-*'if' table*             conditionally assign values to hledger fields,-                         using compact syntax-*'balance-type'*         select which type of balance-                         assertions/assignments to generate-*'include'*              inline another CSV rules file--   Working with CSV tips can be found below, including How CSV rules are-evaluated.---File: hledger.info,  Node: source,  Next: separator,  Prev: CSV rules cheatsheet,  Up: CSV--10.2 'source'-=============--If you tell hledger to read a csv file with '-f foo.csv', it will look-for rules in 'foo.csv.rules'.  Or, you can tell it to read the rules-file, with '-f foo.csv.rules', and it will look for data in 'foo.csv'-(since 1.30).--   These are mostly equivalent, but the second method provides some-extra features.  For one, the data file can be missing, without causing-an error; it is just considered empty.  And, you can specify a different-data file by adding a "source" rule:--source ./Checking1.csv--   If you specify just a file name with no path, hledger will look for-it in your system's downloads directory ('~/Downloads', currently):--source Checking1.csv--   And if you specify a glob pattern, hledger will read the most recent-of the matched files (useful with repeated downloads):--source Checking1*.csv--   See also "Working with CSV > Reading files specified by rule".---File: hledger.info,  Node: separator,  Next: skip,  Prev: source,  Up: CSV--10.3 'separator'-================--You can use the 'separator' rule to read other kinds of-character-separated data.  The argument is any single separator-character, or the words 'tab' or 'space' (case insensitive).  Eg, for-comma-separated values (CSV):--separator ,--   or for semicolon-separated values (SSV):--separator ;--   or for tab-separated values (TSV):--separator TAB--   If the input file has a '.csv', '.ssv' or '.tsv' file extension (or a-'csv:', 'ssv:', 'tsv:' prefix), the appropriate separator will be-inferred automatically, and you won't need this rule.---File: hledger.info,  Node: skip,  Next: date-format,  Prev: separator,  Up: CSV--10.4 'skip'-===========--skip N--   The word 'skip' followed by a number (or no number, meaning 1) tells-hledger to ignore this many non-empty lines at the start of the input-data.  You'll need this whenever your CSV data contains header lines.-Note, empty and blank lines are skipped automatically, so you don't need-to count those.--   'skip' has a second meaning: it can be used inside if blocks-(described below), to skip one or more records whenever the condition is-true.  Records skipped in this way are ignored, except they are still-required to be valid CSV.---File: hledger.info,  Node: date-format,  Next: timezone,  Prev: skip,  Up: CSV--10.5 'date-format'-==================--date-format DATEFMT--   This is a helper for the 'date' (and 'date2') fields.  If your CSV-dates are not formatted like 'YYYY-MM-DD', 'YYYY/MM/DD' or 'YYYY.MM.DD',-you'll need to add a date-format rule describing them with a-strptime-style date parsing pattern - see-https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime.-The pattern must parse the CSV date value completely.  Some examples:--# MM/DD/YY-date-format %m/%d/%y--# D/M/YYYY-# The - makes leading zeros optional.-date-format %-d/%-m/%Y--# YYYY-Mmm-DD-date-format %Y-%h-%d--# M/D/YYYY HH:MM AM some other junk-# Note the time and junk must be fully parsed, though only the date is used.-date-format %-m/%-d/%Y %l:%M %p some other junk---File: hledger.info,  Node: timezone,  Next: newest-first,  Prev: date-format,  Up: CSV--10.6 'timezone'-===============--timezone TIMEZONE--   When CSV contains date-times that are implicitly in some time zone-other than yours, but containing no explicit time zone information, you-can use this rule to declare the CSV's native time zone, which helps-prevent off-by-one dates.--   When the CSV date-times do contain time zone information, you don't-need this rule; instead, use '%Z' in 'date-format' (or '%z', '%EZ',-'%Ez'; see the formatTime link above).--   In either of these cases, hledger will do a time-zone-aware-conversion, localising the CSV date-times to your current system time-zone.  If you prefer to localise to some other time zone, eg for-reproducibility, you can (on unix at least) set the output timezone with-the TZ environment variable, eg:--$ TZ=-1000 hledger print -f foo.csv  # or TZ=-1000 hledger import foo.csv--   'timezone' currently does not understand timezone names, except-"UTC", "GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT".-For others, use numeric format: +HHMM or -HHMM.---File: hledger.info,  Node: newest-first,  Next: intra-day-reversed,  Prev: timezone,  Up: CSV--10.7 'newest-first'-===================--hledger tries to ensure that the generated transactions will be ordered-chronologically, including same-day transactions.  Usually it can-auto-detect how the CSV records are ordered.  But if it encounters CSV-where all records are on the same date, it assumes that the records are-oldest first.  If in fact the CSV's records are normally newest first,-like:--2022-10-01, txn 3...-2022-10-01, txn 2...-2022-10-01, txn 1...--   you can add the 'newest-first' rule to help hledger generate the-transactions in correct order.--# same-day CSV records are newest first-newest-first---File: hledger.info,  Node: intra-day-reversed,  Next: decimal-mark,  Prev: newest-first,  Up: CSV--10.8 'intra-day-reversed'-=========================--If CSV records within a single day are ordered opposite to the overall-record order, you can add the 'intra-day-reversed' rule to improve the-order of journal entries.  Eg, here the overall record order is newest-first, but same-day records are oldest first:--2022-10-02, txn 3...-2022-10-02, txn 4...-2022-10-01, txn 1...-2022-10-01, txn 2...--# transactions within each day are reversed with respect to the overall date order-intra-day-reversed---File: hledger.info,  Node: decimal-mark,  Next: fields list,  Prev: intra-day-reversed,  Up: CSV--10.9 'decimal-mark'-===================--decimal-mark .--   or:--decimal-mark ,--   hledger automatically accepts either period or comma as a decimal-mark when parsing numbers (cf Amounts).  However if any numbers in the-CSV contain digit group marks, such as thousand-separating commas, you-should declare the decimal mark explicitly with this rule, to avoid-misparsed numbers.---File: hledger.info,  Node: fields list,  Next: Field assignment,  Prev: decimal-mark,  Up: CSV--10.10 'fields' list-===================--fields FIELDNAME1, FIELDNAME2, ...--   A fields list (the word 'fields' followed by comma-separated field-names) is optional, but convenient.  It does two things:--  1. It names the CSV field in each column.  This can be convenient if-     you are referencing them in other rules, so you can say-     '%SomeField' instead of remembering '%13'.--  2. Whenever you use one of the special hledger field names (described-     below), it assigns the CSV value in this position to that hledger-     field.  This is the quickest way to populate hledger's fields and-     build a transaction.--   Here's an example that says "use the 1st, 2nd and 4th fields as the-transaction's date, description and amount; name the last two fields for-later reference; and ignore the others":--fields date, description, , amount, , , somefield, anotherfield--   In a fields list, the separator is always comma; it is unrelated to-the CSV file's separator.  Also:--   * There must be least two items in the list (at least one comma).-   * Field names may not contain spaces.  Spaces before/after field-     names are optional.-   * Field names may contain '_' (underscore) or '-' (hyphen).-   * Fields you don't care about can be given a dummy name or an empty-     name.--   If the CSV contains column headings, it's convenient to use these for-your field names, suitably modified (eg lower-cased with spaces replaced-by underscores).--   Sometimes you may want to alter a CSV field name to avoid assigning-to a hledger field with the same name.  Eg you could call the CSV's-"balance" field 'balance_' to avoid directly setting hledger's 'balance'-field (and generating a balance assertion).---File: hledger.info,  Node: Field assignment,  Next: Field names,  Prev: fields list,  Up: CSV--10.11 Field assignment-======================--HLEDGERFIELD FIELDVALUE--   Field assignments are the more flexible way to assign CSV values to-hledger fields.  They can be used instead of or in addition to a fields-list (see above).--   To assign a value to a hledger field, write the field name (any of-the standard hledger field/pseudo-field names, defined below), a space,-followed by a text value on the same line.  This text value may-interpolate CSV fields, referenced either by their 1-based position in-the CSV record ('%N') or by the name they were given in the fields list-('%CSVFIELD'), and regular expression match groups ('\N').--   Some examples:--# set the amount to the 4th CSV field, with " USD" appended-amount %4 USD--# combine three fields to make a comment, containing note: and date: tags-comment note: %somefield - %anotherfield, date: %1--   Tips:--   * Interpolation strips outer whitespace (so a CSV value like '" 1 "'-     becomes '1' when interpolated) (#1051).-   * Interpolations always refer to a CSV field - you can't interpolate-     a hledger field.  (See Referencing other fields below).---File: hledger.info,  Node: Field names,  Next: if block,  Prev: Field assignment,  Up: CSV--10.12 Field names-=================--Note the two kinds of field names mentioned here, and used only in-hledger CSV rules files:--  1. *CSV field names* ('CSVFIELD' in these docs): you can optionally-     name the CSV columns for easy reference (since hledger doesn't yet-     automatically recognise column headings in a CSV file), by writing-     arbitrary names in a 'fields' list, eg:--     fields When, What, Some_Id, Net, Total, Foo, Bar--  2. Special *hledger field names* ('HLEDGERFIELD' in these docs): you-     must set at least some of these to generate the hledger transaction-     from a CSV record, by writing them as the left hand side of a field-     assignment, eg:--     date        %When-     code        %Some_Id-     description %What-     comment     %Foo %Bar-     amount1     $ %Total--     or directly in a 'fields' list:--     fields date, description, code, , amount1, Foo, Bar-     currency $-     comment  %Foo %Bar--   Here are all the special hledger field names available, and what-happens when you assign values to them:--* Menu:--* date field::-* date2 field::-* status field::-* code field::-* description field::-* comment field::-* account field::-* amount field::-* currency field::-* balance field::---File: hledger.info,  Node: date field,  Next: date2 field,  Up: Field names--10.12.1 date field---------------------Assigning to 'date' sets the transaction date.---File: hledger.info,  Node: date2 field,  Next: status field,  Prev: date field,  Up: Field names--10.12.2 date2 field----------------------'date2' sets the transaction's secondary date, if any.---File: hledger.info,  Node: status field,  Next: code field,  Prev: date2 field,  Up: Field names--10.12.3 status field-----------------------'status' sets the transaction's status, if any.---File: hledger.info,  Node: code field,  Next: description field,  Prev: status field,  Up: Field names--10.12.4 code field---------------------'code' sets the transaction's code, if any.---File: hledger.info,  Node: description field,  Next: comment field,  Prev: code field,  Up: Field names--10.12.5 description field----------------------------'description' sets the transaction's description, if any.---File: hledger.info,  Node: comment field,  Next: account field,  Prev: description field,  Up: Field names--10.12.6 comment field------------------------'comment' sets the transaction's comment, if any.--   'commentN', where N is a number, sets the Nth posting's comment.--   You can assign multi-line comments by writing literal '\n' in the-code.  A comment starting with '\n' will begin on a new line.--   Comments can contain tags, as usual.---File: hledger.info,  Node: account field,  Next: amount field,  Prev: comment field,  Up: Field names--10.12.7 account field------------------------Assigning to 'accountN', where N is 1 to 99, sets the account name of-the Nth posting, and causes that posting to be generated.--   Most often there are two postings, so you'll want to set 'account1'-and 'account2'.  Typically 'account1' is associated with the CSV file,-and is set once with a top-level assignment, while 'account2' is set-based on each transaction's description, in conditional rules.--   If a posting's account name is left unset but its amount is set (see-below), a default account name will be chosen (like "expenses:unknown"-or "income:unknown").---File: hledger.info,  Node: amount field,  Next: currency field,  Prev: account field,  Up: Field names--10.12.8 amount field-----------------------There are several ways to set posting amounts from CSV, useful in-different situations.--  1. *'amount'* is the oldest and simplest.  Assigning to this sets the-     amount of the first and second postings.  In the second posting,-     the amount will be negated; also, if it has a cost attached, it-     will be converted to cost.--  2. *'amount-in'* and *'amount-out'* work exactly like the above, but-     should be used when the CSV has two amount fields (such as "Debit"-     and "Credit", or "Inflow" and "Outflow").  Whichever field has a-     non-zero value will be used as the amount of the first and second-     postings.  Here are some tips to avoid confusion:--        * It's not "amount-in for posting 1 and amount-out for posting-          2", it is "extract a single amount from the amount-in or-          amount-out field, and use that for posting 1 and (negated) for-          posting 2".-        * Don't use both 'amount' and 'amount-in'/'amount-out' in the-          same rules file; choose based on whether the amount is in a-          single CSV field or spread across two fields.-        * In each record, at most one of the two CSV fields should-          contain a non-zero amount; the other field must contain a zero-          or nothing.-        * hledger assumes both CSV fields contain unsigned numbers, and-          it automatically negates the amount-out values.-        * If the data doesn't fit these requirements, you'll probably-          need an if rule (see below).--  3. *'amountN'* (where N is a number from 1 to 99) sets the amount of-     only a single posting: the Nth posting in the transaction.  You'll-     usually need at least two such assignments to make a balanced-     transaction.  You can also generate more than two postings, to-     represent more complex transactions.  The posting numbers don't-     have to be consecutive; with if rules, higher posting numbers can-     be useful to ensure a certain order of postings.--  4. *'amountN-in'* and *'amountN-out'* work exactly like the above, but-     should be used when the CSV has two amount fields.  This is-     analogous to 'amount-in' and 'amount-out', and those tips also-     apply here.--  5. Remember that a 'fields' list can also do assignments.  So in a-     fields list if you name a CSV field "amount", that counts as-     assigning to 'amount'.  (If you don't want that, call it something-     else in the fields list, like "amount_".)--  6. The above don't handle every situation; if you need more-     flexibility, use an 'if' rule to set amounts conditionally.  See-     "Working with CSV > Setting amounts" below for more on this and on-     amount-setting generally.---File: hledger.info,  Node: currency field,  Next: balance field,  Prev: amount field,  Up: Field names--10.12.9 currency field-------------------------'currency' sets a currency symbol, to be prepended to all postings'-amounts.  You can use this if the CSV amounts do not have a currency-symbol, eg if it is in a separate column.--   'currencyN' prepends a currency symbol to just the Nth posting's-amount.---File: hledger.info,  Node: balance field,  Prev: currency field,  Up: Field names--10.12.10 balance field-------------------------'balanceN' sets a balance assertion amount (or if the posting amount is-left empty, a balance assignment) on posting N.--   'balance' is a compatibility spelling for hledger <1.17; it is-equivalent to 'balance1'.--   You can adjust the type of assertion/assignment with the-'balance-type' rule (see below).--   See Tips below for more about setting amounts and currency.---File: hledger.info,  Node: if block,  Next: Matchers,  Prev: Field names,  Up: CSV--10.13 'if' block-================--Rules can be applied conditionally, depending on patterns in the CSV-data.  This allows flexibility; in particular, it is how you can-categorise transactions, selecting an appropriate account name based on-their description (for example).  There are two ways to write-conditional rules: "if blocks", described here, and "if tables",-described below.--   An if block is the word 'if' and one or more "matcher" expressions-(can be a word or phrase), one per line, starting either on the same or-next line; followed by one or more indented rules.  Eg,--if MATCHER- RULE--   or--if-MATCHER-MATCHER-MATCHER- RULE- RULE--   If any of the matchers succeeds, all of the indented rules will be-applied.  They are usually field assignments, but the following special-rules may also be used within an if block:--   * 'skip' - skips the matched CSV record (generating no transaction-     from it)-   * 'end' - skips the rest of the current CSV file.--   Some examples:--# if the record contains "groceries", set account2 to "expenses:groceries"-if groceries- account2 expenses:groceries--# if the record contains any of these phrases, set account2 and a transaction comment as shown-if-monthly service fee-atm transaction fee-banking thru software- account2 expenses:business:banking- comment  XXX deductible ? check it--# if an empty record is seen (assuming five fields), ignore the rest of the CSV file-if ,,,,- end---File: hledger.info,  Node: Matchers,  Next: if table,  Prev: if block,  Up: CSV--10.14 Matchers-==============--There are two kinds:--  1. A record matcher is a word or single-line text fragment or regular-     expression ('REGEX'), which hledger will try to match-     case-insensitively anywhere within the CSV record.-     Eg: 'whole foods'--  2. A field matcher is preceded with a percent sign and CSV field name-     ('%CSVFIELD REGEX').  hledger will try to match these just within-     the named CSV field.-     Eg: '%date 2023'--   The regular expression is (as usual in hledger) a POSIX extended-regular expression, that also supports GNU word boundaries ('\b', '\B',-'\<', '\>'), and nothing else.  If you have trouble, see "Regular-expressions" in the hledger manual-(https://hledger.org/hledger.html#regular-expressions).--   With record matchers, it's important to know that the record matched-is not the original CSV record, but a modified one: separators will be-converted to commas, and enclosing double quotes (but not enclosing-whitespace) are removed.  So for example, when reading an SSV file, if-the original record was:--2023-01-01; "Acme, Inc.";  1,000--   the regex would see, and try to match, this modified record text:--2023-01-01,Acme, Inc.,  1,000--   When an if block has multiple matchers, they are combined as follows:--   * By default they are OR'd (any one of them can match)-   * When a matcher is preceded by ampersand ('&') it will be AND'ed-     with the previous matcher (both of them must match).--   When a matcher is preceded by an exclamation mark (!), the matcher-will be negated, ie it will exclude CSV records that match.--* Menu:--* Match groups::---File: hledger.info,  Node: Match groups,  Up: Matchers--10.14.1 Match groups-----------------------Matchers can define match groups: parenthesised portions of the regular-expression which are available for reference in field assignments.-Groups are enclosed in regular parentheses ('(' and ')') and can be-nested.  Each group is available in field assignments using the token-'\N', where N is an index into the match groups for this conditional-block (e.g.  '\1', '\2', etc.).--   Example: Warp credit card payment postings to the beginning of the-billing period (Month start), to match how they are presented in-statements, using posting dates:--if %date (....-..)-..-  comment2 date:\1-01--   Another example: Read the expense account from the CSV field, but-throw away a prefix:--if %account1 liabilities:family:(expenses:.*)-    account1 \1---File: hledger.info,  Node: if table,  Next: balance-type,  Prev: Matchers,  Up: CSV--10.15 'if' table-================--"if tables" are an alternative to if blocks; they can express many-matchers and field assignments in a more compact tabular format, like-this:--if,HLEDGERFIELD1,HLEDGERFIELD2,...-MATCHERA,VALUE1,VALUE2,...-MATCHERB,VALUE1,VALUE2,...-MATCHERC,VALUE1,VALUE2,...-<empty line>--   The first character after 'if' is taken to be this if table's field-separator.  It is unrelated to the separator used in the CSV file.  It-should be a non-alphanumeric character like ',' or '|' that does not-appear anywhere else in the table (it should not be used in field names-or matchers or values, and it cannot be escaped with a backslash).--   Each line must contain the same number of separators; empty values-are allowed.  Whitespace can be used in the matcher lines for-readability (but not in the if line, currently).  The table must be-terminated by an empty line (or end of file).--   An if table like the above is interpreted as follows: try all of the-matchers; whenever a matcher succeeds, assign all of the values on that-line to the corresponding hledger fields; later lines can overrider-earlier ones.  It is equivalent to this sequence of if blocks:--if MATCHERA-  HLEDGERFIELD1 VALUE1-  HLEDGERFIELD2 VALUE2-  ...--if MATCHERB-  HLEDGERFIELD1 VALUE1-  HLEDGERFIELD2 VALUE2-  ...--if MATCHERC-  HLEDGERFIELD1 VALUE1-  HLEDGERFIELD2 VALUE2-  ...--   Example:--if,account2,comment-atm transaction fee,expenses:business:banking,deductible? check it-%description groceries,expenses:groceries,-2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out---File: hledger.info,  Node: balance-type,  Next: include,  Prev: if table,  Up: CSV--10.16 'balance-type'-====================--Balance assertions generated by assigning to balanceN are of the simple-'=' type by default, which is a single-commodity, subaccount-excluding-assertion.  You may find the subaccount-including variants more useful,-eg if you have created some virtual subaccounts of checking to help with-budgeting.  You can select a different type of assertion with the-'balance-type' rule:--# balance assertions will consider all commodities and all subaccounts-balance-type ==*--   Here are the balance assertion types for quick reference:--=    single commodity, exclude subaccounts-=*   single commodity, include subaccounts-==   multi commodity,  exclude subaccounts-==*  multi commodity,  include subaccounts---File: hledger.info,  Node: include,  Next: Working with CSV,  Prev: balance-type,  Up: CSV--10.17 'include'-===============--include RULESFILE--   This includes the contents of another CSV rules file at this point.-'RULESFILE' is an absolute file path or a path relative to the current-file's directory.  This can be useful for sharing common rules between-several rules files, eg:--# someaccount.csv.rules--## someaccount-specific rules-fields   date,description,amount-account1 assets:someaccount-account2 expenses:misc--## common rules-include categorisation.rules---File: hledger.info,  Node: Working with CSV,  Next: CSV rules examples,  Prev: include,  Up: CSV--10.18 Working with CSV-======================--Some tips:--* Menu:--* Rapid feedback::-* Valid CSV::-* File Extension::-* Reading CSV from standard input::-* Reading multiple CSV files::-* Reading files specified by rule::-* Valid transactions::-* Deduplicating importing::-* Setting amounts::-* Amount signs::-* Setting currency/commodity::-* Amount decimal places::-* Referencing other fields::-* How CSV rules are evaluated::-* Well factored rules::---File: hledger.info,  Node: Rapid feedback,  Next: Valid CSV,  Up: Working with CSV--10.18.1 Rapid feedback-------------------------It's a good idea to get rapid feedback while creating/troubleshooting-CSV rules.  Here's a good way, using entr from eradman.com/entrproject:--$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC'--   A desc: query (eg) is used to select just one, or a few, transactions-of interest.  "bash -c" is used to run multiple commands, so we can echo-a separator each time the command re-runs, making it easier to read the-output.---File: hledger.info,  Node: Valid CSV,  Next: File Extension,  Prev: Rapid feedback,  Up: Working with CSV--10.18.2 Valid CSV--------------------Note that hledger will only accept valid CSV conforming to RFC 4180, and-equivalent SSV and TSV formats (like RFC 4180 but with semicolon or tab-as separators).  This means, eg:--   * Values may be enclosed in double quotes, or not.  Enclosing in-     single quotes is not allowed.  (Eg ''A','B'' is rejected.)-   * When values are enclosed in double quotes, spaces outside the-     quotes are not allowed.  (Eg '"A", "B"' is rejected.)-   * When values are not enclosed in quotes, they may not contain double-     quotes.  (Eg 'A"A, B' is rejected.)--   If your CSV/SSV/TSV is not valid in this sense, you'll need to-transform it before reading with hledger.  Try using sed, or a more-permissive CSV parser like python's csv lib.---File: hledger.info,  Node: File Extension,  Next: Reading CSV from standard input,  Prev: Valid CSV,  Up: Working with CSV--10.18.3 File Extension-------------------------To help hledger choose the CSV file reader and show the right error-messages (and choose the right field separator character by default),-it's best if CSV/SSV/TSV files are named with a '.csv', '.ssv' or '.tsv'-filename extension.  (More about this at Data formats.)--   When reading files with the "wrong" extension, you can ensure the CSV-reader (and the default field separator) by prefixing the file path with-'csv:', 'ssv:' or 'tsv:': Eg:--$ hledger -f ssv:foo.dat print--   You can also override the default field separator with a separator-rule if needed.---File: hledger.info,  Node: Reading CSV from standard input,  Next: Reading multiple CSV files,  Prev: File Extension,  Up: Working with CSV--10.18.4 Reading CSV from standard input------------------------------------------You'll need the file format prefix when reading CSV from stdin also,-since hledger assumes journal format by default.  Eg:--$ cat foo.dat | hledger -f ssv:- print---File: hledger.info,  Node: Reading multiple CSV files,  Next: Reading files specified by rule,  Prev: Reading CSV from standard input,  Up: Working with CSV--10.18.5 Reading multiple CSV files-------------------------------------If you use multiple '-f' options to read multiple CSV files at once,-hledger will look for a correspondingly-named rules file for each CSV-file.  But if you use the '--rules-file' option, that rules file will be-used for all the CSV files.---File: hledger.info,  Node: Reading files specified by rule,  Next: Valid transactions,  Prev: Reading multiple CSV files,  Up: Working with CSV--10.18.6 Reading files specified by rule------------------------------------------Instead of specifying a CSV file in the command line, you can specify a-rules file, as in 'hledger -f foo.csv.rules CMD'.  By default this will-read data from foo.csv in the same directory, but you can add a source-rule to specify a different data file, perhaps located in your web-browser's download directory.--   This feature was added in hledger 1.30, so you won't see it in most-CSV rules examples.  But it helps remove some of the busywork of-managing CSV downloads.  Most of your financial institutions's default-CSV filenames are different and can be recognised by a glob pattern.  So-you can put a rule like 'source Checking1*.csv' in-foo-checking.csv.rules, and then periodically follow a workflow like:--  1. Download CSV from Foo's website, using your browser's defaults-  2. Run 'hledger import foo-checking.csv.rules' to import any new-     transactions--   After import, you can: discard the CSV, or leave it where it is for a-while, or move it into your archives, as you prefer.  If you do nothing,-next time your browser will save something like Checking1-2.csv, and-hledger will use that because of the '*' wild card and because it is the-most recent.---File: hledger.info,  Node: Valid transactions,  Next: Deduplicating importing,  Prev: Reading files specified by rule,  Up: Working with CSV--10.18.7 Valid transactions-----------------------------After reading a CSV file, hledger post-processes and validates the-generated journal entries as it would for a journal file - balancing-them, applying balance assignments, and canonicalising amount styles.-Any errors at this stage will be reported in the usual way, displaying-the problem entry.--   There is one exception: balance assertions, if you have generated-them, will not be checked, since normally these will work only when the-CSV data is part of the main journal.  If you do need to check balance-assertions generated from CSV right away, pipe into another hledger:--$ hledger -f file.csv print | hledger -f- print---File: hledger.info,  Node: Deduplicating importing,  Next: Setting amounts,  Prev: Valid transactions,  Up: Working with CSV--10.18.8 Deduplicating, importing-----------------------------------When you download a CSV file periodically, eg to get your latest bank-transactions, the new file may overlap with the old one, containing some-of the same records.--   The import command will (a) detect the new transactions, and (b)-append just those transactions to your main journal.  It is idempotent,-so you don't have to remember how many times you ran it or with which-version of the CSV. (It keeps state in a hidden '.latest.FILE.csv'-file.)  This is the easiest way to import CSV data.  Eg:--# download the latest CSV files, then run this command.-# Note, no -f flags needed here.-$ hledger import *.csv [--dry]--   This method works for most CSV files.  (Where records have a stable-chronological order, and new records appear only at the new end.)--   A number of other tools and workflows, hledger-specific and-otherwise, exist for converting, deduplicating, classifying and managing-CSV data.  See:--   * https://hledger.org/cookbook.html#setups-and-workflows-   * https://plaintextaccounting.org -> data import/conversion---File: hledger.info,  Node: Setting amounts,  Next: Amount signs,  Prev: Deduplicating importing,  Up: Working with CSV--10.18.9 Setting amounts--------------------------Continuing from amount field above, here are more tips for-amount-setting:--  1. *If the amount is in a single CSV field:*--       a. *If its sign indicates direction of flow:*-          Assign it to 'amountN', to set the Nth posting's amount.  N is-          usually 1 or 2 but can go up to 99.--       b. *If another field indicates direction of flow:*-          Use one or more conditional rules to set the appropriate-          amount sign.  Eg:--     # assume a withdrawal unless Type contains "deposit":-     amount1  -%Amount-     if %Type deposit-       amount1  %Amount--  2. *If the amount is in two CSV fields (such as Debit and Credit, or-     In and Out):*--       a. *If both fields are unsigned:*-          Assign one field to 'amountN-in' and the other to-          'amountN-out'.  hledger will automatically negate the "out"-          field, and will use whichever field value is non-zero as-          posting N's amount.--       b. *If either field is signed:*-          You will probably need to override hledger's sign for one or-          the other field, as in the following example:--     # Negate the -out value, but only if it is not empty:-     fields date, description, amount1-in, amount1-out-     if %amount1-out [1-9]-      amount1-out -%amount1-out--       c. *If both fields can contain a non-zero value (or both can be-          empty):*-          The -in/-out rules normally choose the value which is-          non-zero/non-empty.  Some value pairs can be ambiguous, such-          as '1' and 'none'.  For such cases, use conditional rules to-          help select the amount.  Eg, to handle the above you could-          select the value containing non-zero digits:--     fields date, description, in, out-     if %in [1-9]-      amount1 %in-     if %out [1-9]-      amount1 %out--  3. *If you want posting 2's amount converted to cost:*-     Use the unnumbered 'amount' (or 'amount-in' and 'amount-out')-     syntax.--  4. *If the CSV has only balance amounts, not transaction amounts:*-     Assign to 'balanceN', to set a balance assignment on the Nth-     posting, causing the posting's amount to be calculated-     automatically.  'balance' with no number is equivalent to-     'balance1'.  In this situation hledger is more likely to guess the-     wrong default account name, so you may need to set that explicitly.---File: hledger.info,  Node: Amount signs,  Next: Setting currency/commodity,  Prev: Setting amounts,  Up: Working with CSV--10.18.10 Amount signs------------------------There is some special handling making it easier to parse and to reverse-amount signs.  (This only works for whole amounts, not for cost amounts-such as COST in 'amount1 AMT @ COST'):--   * *If an amount value begins with a plus sign:*-     that will be removed: '+AMT' becomes 'AMT'--   * *If an amount value is parenthesised:*-     it will be de-parenthesised and sign-flipped: '(AMT)' becomes-     '-AMT'--   * *If an amount value has two minus signs (or two sets of-     parentheses, or a minus sign and parentheses):*-     they cancel out and will be removed: '--AMT' or '-(AMT)' becomes-     'AMT'--   * *If an amount value contains just a sign (or just a set of-     parentheses):*-     that is removed, making it an empty value.  '"+"' or '"-"' or-     '"()"' becomes '""'.--   It's not possible (without preprocessing the CSV) to set an amount to-its absolute value, ie discard its sign.---File: hledger.info,  Node: Setting currency/commodity,  Next: Amount decimal places,  Prev: Amount signs,  Up: Working with CSV--10.18.11 Setting currency/commodity--------------------------------------If the currency/commodity symbol is included in the CSV's amount-field(s):--2023-01-01,foo,$123.00--   you don't have to do anything special for the commodity symbol, it-will be assigned as part of the amount.  Eg:--fields date,description,amount--2023-01-01 foo-    expenses:unknown         $123.00-    income:unknown          $-123.00--   If the currency is provided as a separate CSV field:--2023-01-01,foo,USD,123.00--   You can assign that to the 'currency' pseudo-field, which has the-special effect of prepending itself to every amount in the transaction-(on the left, with no separating space):--fields date,description,currency,amount--2023-01-01 foo-    expenses:unknown       USD123.00-    income:unknown        USD-123.00--   Or, you can use a field assignment to construct the amount yourself,-with more control.  Eg to put the symbol on the right, and separated by-a space:--fields date,description,cur,amt-amount %amt %cur--2023-01-01 foo-    expenses:unknown        123.00 USD-    income:unknown         -123.00 USD--   Note we used a temporary field name ('cur') that is not 'currency' --that would trigger the prepending effect, which we don't want here.---File: hledger.info,  Node: Amount decimal places,  Next: Referencing other fields,  Prev: Setting currency/commodity,  Up: Working with CSV--10.18.12 Amount decimal places---------------------------------Like amounts in a journal file, the amounts generated by CSV rules like-'amount1' influence commodity display styles, such as the number of-decimal places displayed in reports.--   The original amounts as written in the CSV file do not affect display-style (because we don't yet reliably know their commodity).---File: hledger.info,  Node: Referencing other fields,  Next: How CSV rules are evaluated,  Prev: Amount decimal places,  Up: Working with CSV--10.18.13 Referencing other fields------------------------------------In field assignments, you can interpolate only CSV fields, not hledger-fields.  In the example below, there's both a CSV field and a hledger-field named amount1, but %amount1 always means the CSV field, not the-hledger field:--# Name the third CSV field "amount1"-fields date,description,amount1--# Set hledger's amount1 to the CSV amount1 field followed by USD-amount1 %amount1 USD--# Set comment to the CSV amount1 (not the amount1 assigned above)-comment %amount1--   Here, since there's no CSV amount1 field, %amount1 will produce a-literal "amount1":--fields date,description,csvamount-amount1 %csvamount USD-# Can't interpolate amount1 here-comment %amount1--   When there are multiple field assignments to the same hledger field,-only the last one takes effect.  Here, comment's value will be be B, or-C if "something" is matched, but never A:--comment A-comment B-if something- comment C---File: hledger.info,  Node: How CSV rules are evaluated,  Next: Well factored rules,  Prev: Referencing other fields,  Up: Working with CSV--10.18.14 How CSV rules are evaluated---------------------------------------Here's how to think of CSV rules being evaluated (if you really need-to).  First,--   * 'include' - all includes are inlined, from top to bottom, depth-     first.  (At each include point the file is inlined and scanned for-     further includes, recursively, before proceeding.)--   Then "global" rules are evaluated, top to bottom.  If a rule is-repeated, the last one wins:--   * 'skip' (at top level)-   * 'date-format'-   * 'newest-first'-   * 'fields' - names the CSV fields, optionally sets up initial-     assignments to hledger fields--   Then for each CSV record in turn:--   * test all 'if' blocks.  If any of them contain a 'end' rule, skip-     all remaining CSV records.  Otherwise if any of them contain a-     'skip' rule, skip that many CSV records.  If there are multiple-     matched 'skip' rules, the first one wins.-   * collect all field assignments at top level and in matched 'if'-     blocks.  When there are multiple assignments for a field, keep only-     the last one.-   * compute a value for each hledger field - either the one that was-     assigned to it (and interpolate the %CSVFIELD references), or a-     default-   * generate a hledger transaction (journal entry) from these values.--   This is all part of the CSV reader, one of several readers hledger-can use to parse input files.  When all files have been read-successfully, the transactions are passed as input to whichever hledger-command the user specified.---File: hledger.info,  Node: Well factored rules,  Prev: How CSV rules are evaluated,  Up: Working with CSV--10.18.15 Well factored rules-------------------------------Some things than can help reduce duplication and complexity in rules-files:--   * Extracting common rules usable with multiple CSV files into a-     'common.rules', and adding 'include common.rules' to each CSV's-     rules file.--   * Splitting if blocks into smaller if blocks, extracting the-     frequently used parts.---File: hledger.info,  Node: CSV rules examples,  Prev: Working with CSV,  Up: CSV--10.19 CSV rules examples-========================--* Menu:--* Bank of Ireland::-* Coinbase::-* Amazon::-* Paypal::---File: hledger.info,  Node: Bank of Ireland,  Next: Coinbase,  Up: CSV rules examples--10.19.1 Bank of Ireland--------------------------Here's a CSV with two amount fields (Debit and Credit), and a balance-field, which we can use to add balance assertions, which is not-necessary but provides extra error checking:--Date,Details,Debit,Credit,Balance-07/12/2012,LODGMENT       529898,,10.0,131.21-07/12/2012,PAYMENT,5,,126--# bankofireland-checking.csv.rules--# skip the header line-skip--# name the csv fields, and assign some of them as journal entry fields-fields  date, description, amount-out, amount-in, balance--# We generate balance assertions by assigning to "balance"-# above, but you may sometimes need to remove these because:-#-# - the CSV balance differs from the true balance,-#   by up to 0.0000000000005 in my experience-#-# - it is sometimes calculated based on non-chronological ordering,-#   eg when multiple transactions clear on the same day--# date is in UK/Ireland format-date-format  %d/%m/%Y--# set the currency-currency  EUR--# set the base account for all txns-account1  assets:bank:boi:checking--$ hledger -f bankofireland-checking.csv print-2012-12-07 LODGMENT       529898-    assets:bank:boi:checking         EUR10.0 = EUR131.2-    income:unknown                  EUR-10.0--2012-12-07 PAYMENT-    assets:bank:boi:checking         EUR-5.0 = EUR126.0-    expenses:unknown                  EUR5.0--   The balance assertions don't raise an error above, because we're-reading directly from CSV, but they will be checked if these entries are-imported into a journal file.---File: hledger.info,  Node: Coinbase,  Next: Amazon,  Prev: Bank of Ireland,  Up: CSV rules examples--10.19.2 Coinbase-------------------A simple example with some CSV from Coinbase.  The spot price is-recorded using cost notation.  The legacy 'amount' field name-conveniently sets amount 2 (posting 2's amount) to the total cost.--# Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes-# 2021-12-30T06:57:59Z,Receive,USDC,100,GBP,0.740000,"","","","Received 100.00 USDC from an external account"--# coinbase.csv.rules-skip         1-fields       Timestamp,Transaction_Type,Asset,Quantity_Transacted,Spot_Price_Currency,Spot_Price_at_Transaction,Subtotal,Total,Fees_Spread,Notes-date         %Timestamp-date-format  %Y-%m-%dT%T%Z-description  %Notes-account1     assets:coinbase:cc-amount       %Quantity_Transacted %Asset @ %Spot_Price_at_Transaction %Spot_Price_Currency--$ hledger print -f coinbase.csv-2021-12-30 Received 100.00 USDC from an external account-    assets:coinbase:cc    100 USDC @ 0.740000 GBP-    income:unknown                 -74.000000 GBP---File: hledger.info,  Node: Amazon,  Next: Paypal,  Prev: Coinbase,  Up: CSV rules examples--10.19.3 Amazon-----------------Here we convert amazon.com order history, and use an if block to-generate a third posting if there's a fee.  (In practice you'd probably-get this data from your bank instead, but it's an example.)--"Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID"-"Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL"-"Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL"--# amazon-orders.csv.rules--# skip one header line-skip 1--# name the csv fields, and assign the transaction's date, amount and code.-# Avoided the "status" and "amount" hledger field names to prevent confusion.-fields date, _, toorfrom, name, amzstatus, amzamount, fees, code--# how to parse the date-date-format %b %-d, %Y--# combine two fields to make the description-description %toorfrom %name--# save the status as a tag-comment     status:%amzstatus--# set the base account for all transactions-account1    assets:amazon-# leave amount1 blank so it can balance the other(s).-# I'm assuming amzamount excludes the fees, don't remember--# set a generic account2-account2    expenses:misc-amount2     %amzamount-# and maybe refine it further:-#include categorisation.rules--# add a third posting for fees, but only if they are non-zero.-if %fees [1-9]- account3    expenses:fees- amount3     %fees--$ hledger -f amazon-orders.csv print-2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo.  ; status:Completed-    assets:amazon-    expenses:misc          $20.00--2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc.  ; status:Completed-    assets:amazon-    expenses:misc          $25.00-    expenses:fees           $1.00---File: hledger.info,  Node: Paypal,  Prev: Amazon,  Up: CSV rules examples--10.19.4 Paypal-----------------Here's a real-world rules file for (customised) Paypal CSV, with some-Paypal-specific rules, and a second rules file included:--"Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"-"10/01/2019","03:46:20","PDT","Calm Radio","Subscription Payment","Completed","USD","-6.99","0.00","-6.99","simon@joyful.com","memberships@calmradio.com","60P57143A8206782E","MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month","","I-R8YLY094FJYR","","-6.99",""-"10/01/2019","03:46:20","PDT","","Bank Deposit to PP Account ","Pending","USD","6.99","0.00","6.99","","simon@joyful.com","0TU1544T080463733","","","60P57143A8206782E","","0.00",""-"10/01/2019","08:57:01","PDT","Patreon","PreApproved Payment Bill User Payment","Completed","USD","-7.00","0.00","-7.00","simon@joyful.com","support@patreon.com","2722394R5F586712G","Patreon* Membership","","B-0PG93074E7M86381M","","-7.00",""-"10/01/2019","08:57:01","PDT","","Bank Deposit to PP Account ","Pending","USD","7.00","0.00","7.00","","simon@joyful.com","71854087RG994194F","Patreon* Membership","","2722394R5F586712G","","0.00",""-"10/19/2019","03:02:12","PDT","Wikimedia Foundation, Inc.","Subscription Payment","Completed","USD","-2.00","0.00","-2.00","simon@joyful.com","tle@wikimedia.org","K9U43044RY432050M","Monthly donation to the Wikimedia Foundation","","I-R5C3YUS3285L","","-2.00",""-"10/19/2019","03:02:12","PDT","","Bank Deposit to PP Account ","Pending","USD","2.00","0.00","2.00","","simon@joyful.com","3XJ107139A851061F","","","K9U43044RY432050M","","0.00",""-"10/22/2019","05:07:06","PDT","Noble Benefactor","Subscription Payment","Completed","USD","10.00","-0.59","9.41","noble@bene.fac.tor","simon@joyful.com","6L8L1662YP1334033","Joyful Systems","","I-KC9VBGY2GWDB","","9.41",""--# paypal-custom.csv.rules--# Tips:-# Export from Activity -> Statements -> Custom -> Activity download-# Suggested transaction type: "Balance affecting"-# Paypal's default fields in 2018 were:-# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Shipping Address","Address Status","Item Title","Item ID","Shipping and Handling Amount","Insurance Amount","Sales Tax","Option 1 Name","Option 1 Value","Option 2 Name","Option 2 Value","Reference Txn ID","Invoice Number","Custom Number","Quantity","Receipt ID","Balance","Address Line 1","Address Line 2/District/Neighborhood","Town/City","State/Province/Region/County/Territory/Prefecture/Republic","Zip/Postal Code","Country","Contact Phone Number","Subject","Note","Country Code","Balance Impact"-# This rules file assumes the following more detailed fields, configured in "Customize report fields":-# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"--fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note--skip  1--date-format  %-m/%-d/%Y--# ignore some paypal events-if-In Progress-Temporary Hold-Update to- skip--# add more fields to the description-description %description_ %itemtitle--# save some other fields as tags-comment  itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_--# convert to short currency symbols-if %currency USD- currency $-if %currency EUR- currency E-if %currency GBP- currency P--# generate postings--# the first posting will be the money leaving/entering my paypal account-# (negative means leaving my account, in all amount fields)-account1 assets:online:paypal-amount1  %netamount--# the second posting will be money sent to/received from other party-# (account2 is set below)-amount2  -%grossamount--# if there's a fee, add a third posting for the money taken by paypal.-if %feeamount [1-9]- account3 expenses:banking:paypal- amount3  -%feeamount- comment3 business:--# choose an account for the second posting--# override the default account names:-# if the amount is positive, it's income (a debit)-if %grossamount ^[^-]- account2 income:unknown-# if negative, it's an expense (a credit)-if %grossamount ^-- account2 expenses:unknown--# apply common rules for setting account2 & other tweaks-include common.rules--# apply some overrides specific to this csv--# Transfers from/to bank. These are usually marked Pending,-# which can be disregarded in this case.-if-Bank Account-Bank Deposit to PP Account- description %type for %referencetxnid %itemtitle- account2 assets:bank:wf:pchecking- account1 assets:online:paypal--# Currency conversions-if Currency Conversion- account2 equity:currency conversion--# common.rules--if-darcs-noble benefactor- account2 revenues:foss donations:darcshub- comment2 business:--if-Calm Radio- account2 expenses:online:apps--if-electronic frontier foundation-Patreon-wikimedia-Advent of Code- account2 expenses:dues--if Google- account2 expenses:online:apps- description google | music--$ hledger -f paypal-custom.csv  print-2019-10-01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month  ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed-    assets:online:paypal          $-6.99 = $-6.99-    expenses:online:apps           $6.99--2019-10-01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E  ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending-    assets:online:paypal               $6.99 = $0.00-    assets:bank:wf:pchecking          $-6.99--2019-10-01 (2722394R5F586712G) Patreon Patreon* Membership  ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed-    assets:online:paypal          $-7.00 = $-7.00-    expenses:dues                  $7.00--2019-10-01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership  ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending-    assets:online:paypal               $7.00 = $0.00-    assets:bank:wf:pchecking          $-7.00--2019-10-19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation  ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed-    assets:online:paypal             $-2.00 = $-2.00-    expenses:dues                     $2.00-    expenses:banking:paypal      ; business:--2019-10-19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M  ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending-    assets:online:paypal               $2.00 = $0.00-    assets:bank:wf:pchecking          $-2.00--2019-10-22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems  ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed-    assets:online:paypal                       $9.41 = $9.41-    revenues:foss donations:darcshub         $-10.00  ; business:-    expenses:banking:paypal                    $0.59  ; business:---File: hledger.info,  Node: Timeclock,  Next: Timedot,  Prev: CSV,  Up: Top--11 Timeclock-************--The time logging format of timeclock.el, as read by hledger.--   hledger can read time logs in timeclock format.  As with Ledger,-these are (a subset of) timeclock.el's format, containing clock-in and-clock-out entries as in the example below.  The date is a simple date.-The time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are-optional.  The timezone, if present, must be four digits and is ignored-(currently the time is always interpreted as a local time).  Lines-beginning with '#' or ';' or '*', and blank lines, are ignored.--i 2015/03/30 09:00:00 some account  optional description after 2 spaces ; optional comment, tags:-o 2015/03/30 09:20:00-i 2015/03/31 22:21:45 another:account-o 2015/04/01 02:00:34--   hledger treats each clock-in/clock-out pair as a transaction posting-some number of hours to an account.  Or if the session spans more than-one day, it is split into several transactions, one for each day.  For-the above time log, 'hledger print' generates these journal entries:--$ hledger -f t.timeclock print-2015-03-30 * optional description after 2 spaces   ; optional comment, tags:-    (some account)           0.33h--2015-03-31 * 22:21-23:59-    (another:account)           1.64h--2015-04-01 * 00:00-02:00-    (another:account)           2.01h--   Here is a sample.timeclock to download and some queries to try:--$ hledger -f sample.timeclock balance                               # current time balances-$ hledger -f sample.timeclock register -p 2009/3                    # sessions in march 2009-$ hledger -f sample.timeclock register -p weekly --depth 1 --empty  # time summary by week--   To generate time logs, ie to clock in and clock out, you could:--   * use emacs and the built-in timeclock.el, or the extended-     timeclock-x.el and perhaps the extras in ledgerutils.el--   * at the command line, use these bash aliases: 'shell alias ti="echo-     i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o-     `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"'--   * or use the old 'ti' and 'to' scripts in the ledger 2.x repository.-     These rely on a "timeclock" executable which I think is just the-     ledger 2 executable renamed.---File: hledger.info,  Node: Timedot,  Next: PART 3 REPORTING CONCEPTS,  Prev: Timeclock,  Up: Top--12 Timedot-**********--'timedot' format is hledger's human-friendly time logging format.-Compared to 'timeclock' format, it is more convenient for quick,-approximate, and retroactive time logging, and more human-readable (you-can see at a glance where time was spent).  A quick example:--2023-05-01-hom:errands          .... ....  ; two hours; the space is ignored-fos:hledger:timedot  ..         ; half an hour-per:admin:finance               ; no time spent yet--   hledger reads this as a transaction on this day with three-(unbalanced) postings, where each dot represents "0.25".  No commodity-symbol is assumed, but we typically interpret it as hours.--$ hledger -f a.timedot print   # .timedot file extension (or timedot: prefix) is required-2023-05-01 *-    (hom:errands)                    2.00  ; two hours-    (fos:hledger:timedot)            0.50  ; half an hour-    (per:admin:finance)                 0--   A timedot file contains a series of transactions (usually one per-day).  Each begins with a *simple date* (Y-M-D, Y/M/D, or Y.M.D),-optionally be followed on the same line by a transaction description,-and/or a transaction comment following a semicolon.--   After the date line are zero or more time postings, consisting of:--   * *An account name* - any hledger-style account name, optionally-     indented.--   * *Two or more spaces* - required if there is an amount (as in-     journal format).--   * *A timedot amount*, which can be--        * empty (representing zero)--        * a number, optionally followed by a unit 's', 'm', 'h', 'd',-          'w', 'mo', or 'y', representing a precise number of seconds,-          minutes, hours, days weeks, months or years (hours is assumed-          by default), which will be converted to hours according to 60s-          = 1m, 60m = 1h, 24h = 1d, 7d = 1w, 30d = 1mo, 365d = 1y.--        * one or more dots (period characters), each representing 0.25.-          These are the dots in "timedot".  Spaces are ignored and can-          be used for grouping/alignment.--        * one or more letters.  These are like dots but they also-          generate a tag 't:' (short for "type") with the letter as its-          value, and a separate posting for each of the values.  This-          provides a second dimension of categorisation, viewable in-          reports with '--pivot t'.--   * *An optional comment* following a semicolon (a hledger-style-     posting comment).--   There is some flexibility to help with keeping time log data and-notes in the same file:--   * Blank lines and lines beginning with '#' or ';' are ignored.--   * After the first date line, lines which do not contain a double-     space are parsed as postings with zero amount.  (hledger's register-     reports will show these if you add -E).--   * Before the first date line, lines beginning with '*' (eg org-     headings) are ignored.  And from the first date line onward, Emacs-     org mode heading prefixes at the start of lines (one or more '*''s-     followed by a space) will be ignored.  This means the time log can-     also be a org outline.--* Menu:--* Timedot examples::---File: hledger.info,  Node: Timedot examples,  Up: Timedot--12.1 Timedot examples-=====================--Numbers:--2016/2/3-inc:client1   4-fos:hledger   3h-biz:research  60m--   Dots:--# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.-2016/2/1-inc:client1   .... .... .... .... .... ....-fos:haskell   .... ..-biz:research  .--2016/2/2-inc:client1   .... ....-biz:research  .--$ hledger -f a.timedot print date:2016/2/2-2016-02-02 *-    (inc:client1)          2.00--2016-02-02 *-    (biz:research)          0.25--$ hledger -f a.timedot bal --daily --tree-Balance changes in 2016-02-01-2016-02-03:--            ||  2016-02-01d  2016-02-02d  2016-02-03d -============++========================================- biz        ||         0.25         0.25         1.00 -   research ||         0.25         0.25         1.00 - fos        ||         1.50            0         3.00 -   haskell  ||         1.50            0            0 -   hledger  ||            0            0         3.00 - inc        ||         6.00         2.00         4.00 -   client1  ||         6.00         2.00         4.00 -------------++-----------------------------------------            ||         7.75         2.25         8.00 --   Letters:--# Activity types:-#  c cleanup/catchup/repair-#  e enhancement-#  s support-#  l learning/research--2023-11-01-work:adm  ccecces--$ hledger -f a.timedot print-2023-11-01-    (work:adm)  1     ; t:c-    (work:adm)  0.5   ; t:e-    (work:adm)  0.25  ; t:s--$ hledger -f a.timedot bal-                1.75  work:adm----------------------                1.75  --$ hledger -f a.timedot bal --pivot t-                1.00  c-                0.50  e-                0.25  s----------------------                1.75  --   Org:--* 2023 Work Diary-** Q1-*** 2023-02-29-**** DONE-0700 yoga-**** UNPLANNED-**** BEGUN-hom:chores- cleaning  ...- water plants-  outdoor - one full watering can-  indoor - light watering-**** TODO-adm:planning: trip-*** LATER--   Using '.' as account name separator:--2016/2/4-fos.hledger.timedot  4h-fos.ledger           ..--$ hledger -f a.timedot --alias '/\./=:' bal -t-                4.50  fos-                4.00    hledger:timedot-                0.50    ledger----------------------                4.50---File: hledger.info,  Node: PART 3 REPORTING CONCEPTS,  Next: Amount formatting parseability,  Prev: Timedot,  Up: Top--13 PART 3: REPORTING CONCEPTS-*****************************---File: hledger.info,  Node: Amount formatting parseability,  Next: Time periods,  Prev: PART 3 REPORTING CONCEPTS,  Up: Top--14 Amount formatting, parseability-**********************************--If you're wondering why your 'print' report sometimes shows trailing-decimal marks, with no decimal digits; it does this when showing amounts-that have digit group marks but no decimal digits, to disambiguate them-and allow them to be re-parsed reliably (see also Decimal marks, digit-group marks.  Eg:--commodity $1,000.00--2023-01-02-    (a)      $1000--$ hledger print-2023-01-02-    (a)        $1,000.--   If this is a problem (eg when exporting to Ledger), you can avoid it-by disabling digit group marks, eg with -c/-commodity (for each affected-commodity):--$ hledger print -c '$1000.00'-2023-01-02-    (a)          $1000--   or by forcing print to always show decimal digits, with -round:--$ hledger print -c '$1,000.00' --round=soft-2023-01-02-    (a)      $1,000.00--   More generally: hledger output falls into three rough categories,-which format amounts a little bit differently to suit different-consumers:--   *1.  "hledger-readable output" - should be readable by hledger (and-by humans)*--   * This is produced by reports that show full journal entries:-     'print', 'import', 'close', 'rewrite' etc.-   * It shows amounts with their original journal precisions, which may-     not be consistent.-   * It adds a trailing decimal mark when needed to avoid showing-     ambiguous amounts.-   * It can be parsed reliably (by hledger and ledger2beancount at-     least, but perhaps not by Ledger..)--   *2.  "human-readable output" - usually for humans*--   * This is produced by all other reports.-   * It shows amounts with standard display precisions, which will be-     consistent within each commodity.-   * It shows ambiguous amounts unmodified.-   * It can be parsed reliably in the context of a known report (when-     you know decimals are consistently not being shown, you can assume-     a single mark is a digit group mark).--   *3.  "machine-readable output" - usually for other software*--   * This is produced by all reports when an output format like 'csv',-     'tsv', 'json', or 'sql' is selected.-   * It shows amounts as 1 or 2 do, but without digit group marks.-   * It can be parsed reliably (if needed, the decimal mark can be-     changed with -c/-commodity-style).---File: hledger.info,  Node: Time periods,  Next: Depth,  Prev: Amount formatting parseability,  Up: Top--15 Time periods-***************--* Menu:--* Report start & end date::-* Smart dates::-* Report intervals::-* Date adjustment::-* Period expressions::---File: hledger.info,  Node: Report start & end date,  Next: Smart dates,  Up: Time periods--15.1 Report start & end date-============================--By default, most hledger reports will show the full span of time-represented by the journal.  The report start date will be the earliest-transaction or posting date, and the report end date will be the latest-transaction, posting, or market price date.--   Often you will want to see a shorter time span, such as the current-month.  You can specify a start and/or end date using '-b/--begin',-'-e/--end', '-p/--period' or a 'date:' query (described below).  All of-these accept the smart date syntax (below).--   Some notes:--   * End dates are exclusive, as in Ledger, so you should write the date-     _after_ the last day you want to see in the report.-   * As noted in reporting options: among start/end dates specified with-     _options_, the last (i.e.  right-most) option takes precedence.-   * The effective report start and end dates are the intersection of-     the start/end dates from options and that from 'date:' queries.-     That is, 'date:2019-01 date:2019 -p'2000 to 2030'' yields January-     2019, the smallest common time span.-   * In some cases a report interval will adjust start/end dates to fall-     on interval boundaries (see below).--   Examples:--'-b           begin on St. Patrick's day 2016-2016/3/17'-'-e 12/1'     end at the start of december 1st of the current year-              (11/30 will be the last date included)-'-b           all transactions on or after the 1st of the current month-thismonth'-'-p           all transactions in the current month-thismonth'-'date:2016/3/17..'the above written as queries instead ('..' can also be-              replaced with '-')-'date:..12/1'-'date:thismonth..'-'date:thismonth'---File: hledger.info,  Node: Smart dates,  Next: Report intervals,  Prev: Report start & end date,  Up: Time periods--15.2 Smart dates-================--hledger's user interfaces accept a "smart date" syntax for added-convenience.  Smart dates optionally can be relative to today's date, be-written with english words, and have less-significant parts omitted-(missing parts are inferred as 1).  Some examples:--'2004/10/1',              exact date, several separators allowed.  Year-'2004-01-01',             is 4+ digits, month is 1-12, day is 1-31-'2004.9.1'-'2004'                    start of year-'2004/10'                 start of month-'10/1'                    month and day in current year-'21'                      day in current month-'october, oct'            start of month in current year-'yesterday, today,        -1, 0, 1 days from today-tomorrow'-'last/this/next           -1, 0, 1 periods from the current period-day/week/month/quarter/year'-'in n                     n periods from the current period-days/weeks/months/quarters/years'-'n                        n periods from the current period-days/weeks/months/quarters/years-ahead'-'n                        -n periods from the current period-days/weeks/months/quarters/years-ago'-'20181201'                8 digit YYYYMMDD with valid year month and-                          day-'201812'                  6 digit YYYYMM with valid year and month--   Some counterexamples - malformed digit sequences might give-surprising results:--'201813'     6 digits with an invalid month is parsed as start of-             6-digit year-'20181301'   8 digits with an invalid month is parsed as start of-             8-digit year-'20181232'   8 digits with an invalid day gives an error-'201801012'  9+ digits beginning with a valid YYYYMMDD gives an error--   "Today's date" can be overridden with the '--today' option, in case-it's needed for testing or for recreating old reports.  (Except for-periodic transaction rules, which are not affected by '--today'.)---File: hledger.info,  Node: Report intervals,  Next: Date adjustment,  Prev: Smart dates,  Up: Time periods--15.3 Report intervals-=====================--A report interval can be specified so that reports like register,-balance or activity become multi-period, showing each subperiod as a-separate row or column.--   The following standard intervals can be enabled with command-line-flags:--   * '-D/--daily'-   * '-W/--weekly'-   * '-M/--monthly'-   * '-Q/--quarterly'-   * '-Y/--yearly'--   More complex intervals can be specified using '-p/--period',-described below.---File: hledger.info,  Node: Date adjustment,  Next: Period expressions,  Prev: Report intervals,  Up: Time periods--15.4 Date adjustment-====================--When there is a report interval (other than daily), report start/end-dates which have been inferred, eg from the journal, are automatically-adjusted to natural period boundaries.  This is convenient for producing-simple periodic reports.  More precisely:--   * an inferred start date will be adjusted earlier if needed to fall-     on a natural period boundary--   * an inferred end date will be adjusted later if needed to make the-     last period the same length as the others.--   By contrast, start/end dates which have been specified explicitly,-with '-b', '-e', '-p' or 'date:', will not be adjusted (since hledger-1.29).  This makes it possible to specify non-standard report periods,-but it also means that if you are specifying a start date, you should-pick one that's on a period boundary if you want to see simple report-period headings.---File: hledger.info,  Node: Period expressions,  Prev: Date adjustment,  Up: Time periods--15.5 Period expressions-=======================--The '-p/--period' option specifies a period expression, which is a-compact way of expressing a start date, end date, and/or report-interval.--   Here's a period expression with a start and end date (specifying the-first quarter of 2009):--'-p "from 2009/1/1 to 2009/4/1"'--   Several keywords like "from" and "to" are supported for readability;-these are optional.  "to" can also be written as ".."  or "-".  The-spaces are also optional, as long as you don't run two dates together.-So the following are equivalent to the above:--'-p "2009/1/1 2009/4/1"'-'-p2009/1/1to2009/4/1'-'-p2009/1/1..2009/4/1'--   Dates are smart dates, so if the current year is 2009, these are also-equivalent to the above:--'-p "1/1 4/1"'-'-p "jan-apr"'-'-p "this year to 4/1"'--   If you specify only one date, the missing start or end date will be-the earliest or latest transaction date in the journal:--'-p "from 2009/1/1"'   everything after january 1, 2009-'-p "since 2009/1"'    the same, since is a synonym-'-p "from 2009"'       the same-'-p "to 2009"'         everything before january 1, 2009--   You can also specify a period by writing a single partial or full-date:--'-p "2009"'     the year 2009; equivalent to “2009/1/1 to 2010/1/1”-'-p "2009/1"'   the month of january 2009; equivalent to “2009/1/1 to-                2009/2/1”-'-p             the first day of 2009; equivalent to “2009/1/1 to-"2009/1/1"'     2009/1/2”--   or by using the "Q" quarter-year syntax (case insensitive):--'-p "2009Q1"'    first quarter of 2009, equivalent to “2009/1/1 to-                 2009/4/1”-'-p "q4"'        fourth quarter of the current year--* Menu:--* Period expressions with a report interval::-* More complex report intervals::-* Multiple weekday intervals::---File: hledger.info,  Node: Period expressions with a report interval,  Next: More complex report intervals,  Up: Period expressions--15.5.1 Period expressions with a report interval---------------------------------------------------A period expression can also begin with a report interval, separated-from the start/end dates (if any) by a space or the word 'in':--'-p "weekly from 2009/1/1 to 2009/4/1"'-'-p "monthly in 2008"'-'-p "quarterly"'---File: hledger.info,  Node: More complex report intervals,  Next: Multiple weekday intervals,  Prev: Period expressions with a report interval,  Up: Period expressions--15.5.2 More complex report intervals---------------------------------------Some more complex intervals can be specified within period expressions,-such as:--   * 'biweekly' (every two weeks)-   * 'fortnightly'-   * 'bimonthly' (every two months)-   * 'every day|week|month|quarter|year'-   * 'every N days|weeks|months|quarters|years'--   Weekly on a custom day:--   * 'every Nth day of week' ('th', 'nd', 'rd', or 'st' are all accepted-     after the number)-   * 'every WEEKDAYNAME' (full or three-letter english weekday name,-     case insensitive)--   Monthly on a custom day:--   * 'every Nth day [of month]'-   * 'every Nth WEEKDAYNAME [of month]'--   Yearly on a custom day:--   * 'every MM/DD [of year]' (month number and day of month number)-   * 'every MONTHNAME DDth [of year]' (full or three-letter english-     month name, case insensitive, and day of month number)-   * 'every DDth MONTHNAME [of year]' (equivalent to the above)--   Examples:--'-p "bimonthly from-2008"'-'-p "every 2 weeks"'-'-p "every 5 months from-2009/03"'-'-p "every 2nd day of       periods will go from Tue to Tue-week"'-'-p "every Tue"'            same-'-p "every 15th day"'       period boundaries will be on 15th of each-                            month-'-p "every 2nd Monday"'     period boundaries will be on second Monday-                            of each month-'-p "every 11/05"'          yearly periods with boundaries on 5th of-                            November-'-p "every 5th November"'   same-'-p "every Nov 5th"'        same--   Show historical balances at end of the 15th day of each month (N is-an end date, exclusive as always):--$ hledger balance -H -p "every 16th day"--   Group postings from the start of wednesday to end of the following-tuesday (N is both (inclusive) start date and (exclusive) end date):--$ hledger register checking -p "every 3rd day of week"---File: hledger.info,  Node: Multiple weekday intervals,  Prev: More complex report intervals,  Up: Period expressions--15.5.3 Multiple weekday intervals------------------------------------This special form is also supported:--   * 'every WEEKDAYNAME,WEEKDAYNAME,...' (full or three-letter english-     weekday names, case insensitive)--   Also, 'weekday' and 'weekendday' are shorthand for-'mon,tue,wed,thu,fri' and 'sat,sun'.--   This is mainly intended for use with '--forecast', to generate-periodic transactions on arbitrary days of the week.  It may be less-useful with '-p', since it divides each week into subperiods of unequal-length, which is unusual.  (Related: #1632)--   Examples:--'-p "every         dates will be Mon, Wed, Fri; periods will be-mon,wed,fri"'      Mon-Tue, Wed-Thu, Fri-Sun-'-p "every         dates will be Mon, Tue, Wed, Thu, Fri; periods will-weekday"'          be Mon, Tue, Wed, Thu, Fri-Sun-'-p "every         dates will be Sat, Sun; periods will be Sat, Sun-Fri-weekendday"'---File: hledger.info,  Node: Depth,  Next: Queries,  Prev: Time periods,  Up: Top--16 Depth-********--With the '--depth NUM' option (short form: '-NUM'), reports will show-accounts only to the specified depth, hiding deeper subaccounts.  Use-this when you want a summary with less detail.  This flag has the same-effect as a 'depth:' query argument: 'depth:2', '--depth=2' or '-2' are-equivalent.---File: hledger.info,  Node: Queries,  Next: Pivoting,  Prev: Depth,  Up: Top--17 Queries-**********--One of hledger's strengths is being able to quickly report on a precise-subset of your data.  Most hledger commands accept optional query-arguments to restrict their scope.  The syntax is as follows:--   * Zero or more space-separated query terms.  These are most often-     account name substrings:--     'utilities food:groceries'--   * Terms with spaces or other special characters should be enclosed in-     quotes:--     '"personal care"'--   * Regular expressions are also supported:--     '"^expenses\b"'-     '"accounts (payable|receivable)"'--   * Add a query type prefix to match other parts of the data:--     'date:202312-'-     'status:'-     'desc:amazon'-     'cur:USD'-     '"amt:>0"'--   * Add a 'not:' prefix to negate:--     'not:cur:USD'--   * Multiple unlike terms are AND-ed, multiple like terms are OR-ed--     'date:2022 desc:amazon desc:amzn'-     (all transactions with "amazon" or "amzn" in description during-     2022)--* Menu:--* Query types::-* Combining query terms::-* Queries and command options::-* Queries and valuation::-* Querying with account aliases::-* Querying with cost or value::---File: hledger.info,  Node: Query types,  Next: Combining query terms,  Up: Queries--17.1 Query types-================--Here are the types of query term available.  Remember these can also be-prefixed with *'not:'* to convert them into a negative match.--   *'acct:REGEX', 'REGEX'*-Match account names containing this (case insensitive) regular-expression.  This is the default query type when there is no prefix, and-regular expression syntax is typically not needed, so usually we just-write an account name substring, like 'expenses' or 'food'.--   *'amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N'*-Match postings with a single-commodity amount equal to, less than, or-greater than N. (Postings with multi-commodity amounts are not tested-and will always match.)  The comparison has two modes: if N is preceded-by a + or - sign (or is 0), the two signed numbers are compared.-Otherwise, the absolute magnitudes are compared, ignoring sign.--   *'code:REGEX'*-Match by transaction code (eg check number).--   *'cur:REGEX'*-Match postings or transactions including any amounts whose-currency/commodity symbol is fully matched by REGEX. (For a partial-match, use '.*REGEX.*').  Note, to match special characters which are-regex-significant, you need to escape them with '\'.  And for characters-which are significant to your shell you may need one more level of-escaping.  So eg to match the dollar sign:-'hledger print cur:\\$'.--   *'desc:REGEX'*-Match transaction descriptions.--   *'date:PERIODEXPR'*-Match dates (or with the '--date2' flag, secondary dates) within the-specified period.  PERIODEXPR is a period expression with no report-interval.  Examples:-'date:2016', 'date:thismonth', 'date:2/1-2/15',-'date:2021-07-27..nextquarter'.--   *'date2:PERIODEXPR'*-Match secondary dates within the specified period (independent of the-'--date2' flag).--   *'depth:N'*-Match (or display, depending on command) accounts at or above this-depth.--   *'expr:"TERM AND NOT (TERM OR TERM)"'* (eg)-Match with a boolean combination of queries (which must be enclosed in-quotes).  See Combining query terms below.--   *'note:REGEX'*-Match transaction notes (the part of the description right of '|', or-the whole description if there's no '|').--   *'payee:REGEX'*-Match transaction payee/payer names (the part of the description left of-'|', or the whole description if there's no '|').--   *'real:, real:0'*-Match real or virtual postings respectively.--   *'status:, status:!, status:*'*-Match unmarked, pending, or cleared transactions respectively.--   *'type:TYPECODES'*-Match by account type (see Declaring accounts > Account types).-'TYPECODES' is one or more of the single-letter account type codes-'ALERXCV', case insensitive.  Note 'type:A' and 'type:E' will also match-their respective subtypes 'C' (Cash) and 'V' (Conversion).  Certain-kinds of account alias can disrupt account types, see Rewriting accounts-> Aliases and account types.--   *'tag:REGEX[=REGEX]'*-Match by tag name, and optionally also by tag value.  (To match only by-value, use 'tag:.=REGEX'.)--   When querying by tag, note that:--   * Accounts also inherit the tags of their parent accounts-   * Postings also inherit the tags of their account and their-     transaction-   * Transactions also acquire the tags of their postings.--   (*'inacct:ACCTNAME'*-A special query term used automatically in hledger-web only: tells-hledger-web to show the transaction register for an account.)---File: hledger.info,  Node: Combining query terms,  Next: Queries and command options,  Prev: Query types,  Up: Queries--17.2 Combining query terms-==========================--When given multiple space-separated query terms, most commands select-things which match:--   * any of the description terms AND-   * any of the account terms AND-   * any of the status terms AND-   * all the other terms.--   The print command is a little different, showing transactions which:--   * match any of the description terms AND-   * have any postings matching any of the positive account terms AND-   * have no postings matching any of the negative account terms AND-   * match all the other terms.--   We also support more complex boolean queries with the 'expr:' prefix.-This allows one to combine queries using one of three operators: AND,-OR, and NOT, where NOT is different syntax for 'not:'.--   Examples of such queries are:--   * Match transactions with 'cool' in the description AND with the 'A'-     tag--     'expr:"desc:cool AND tag:A"'--   * Match transactions NOT to the 'expenses:food' account OR with the-     'A' tag--     'expr:"NOT expenses:food OR tag:A"'--   * Match transactions NOT involving the 'expenses:food' account OR-     with the 'A' tag AND involving the 'expenses:drink' account.  (the-     AND is implicitly added by space-separation, following the rules-     above)--     'expr:"expenses:food OR (tag:A expenses:drink)"'---File: hledger.info,  Node: Queries and command options,  Next: Queries and valuation,  Prev: Combining query terms,  Up: Queries--17.3 Queries and command options-================================--Some queries can also be expressed as command-line options: 'depth:2' is-equivalent to '--depth 2', 'date:2023' is equivalent to '-p 2023', etc.-When you mix command options and query arguments, generally the-resulting query is their intersection.---File: hledger.info,  Node: Queries and valuation,  Next: Querying with account aliases,  Prev: Queries and command options,  Up: Queries--17.4 Queries and valuation-==========================--When amounts are converted to other commodities in cost or value-reports, 'cur:' and 'amt:' match the old commodity symbol and the old-amount quantity, not the new ones (except in hledger 1.22.0 where it's-reversed, see #1625).---File: hledger.info,  Node: Querying with account aliases,  Next: Querying with cost or value,  Prev: Queries and valuation,  Up: Queries--17.5 Querying with account aliases-==================================--When account names are rewritten with '--alias' or 'alias', note that-'acct:' will match either the old or the new account name.---File: hledger.info,  Node: Querying with cost or value,  Prev: Querying with account aliases,  Up: Queries--17.6 Querying with cost or value-================================--When amounts are converted to other commodities in cost or value-reports, note that 'cur:' matches the new commodity symbol, and not the-old one, and 'amt:' matches the new quantity, and not the old one.-Note: this changed in hledger 1.22, previously it was the reverse, see-the discussion at #1625.---File: hledger.info,  Node: Pivoting,  Next: Generating data,  Prev: Queries,  Up: Top--18 Pivoting-***********--Normally, hledger groups and sums amounts within each account.  The-'--pivot FIELD' option substitutes some other transaction field for-account names, causing amounts to be grouped and summed by that field's-value instead.  FIELD can be any of the transaction fields 'acct',-'status', 'code', 'desc', 'payee', 'note', or a tag name.  When pivoting-on a tag and a posting has multiple values of that tag, only the first-value is displayed.  Values containing 'colon:separated:parts' will be-displayed hierarchically, like account names.  Multiple, colon-delimited-fields can be pivoted simultaneously, generating a hierarchical account-name.--   Some examples:--2016/02/16 Yearly Dues Payment-    assets:bank account                 2 EUR-    income:dues                        -2 EUR  ; member: John Doe, kind: Lifetime--   Normal balance report showing account names:--$ hledger balance-               2 EUR  assets:bank account-              -2 EUR  income:dues----------------------                   0--   Pivoted balance report, using member: tag values instead:--$ hledger balance --pivot member-               2 EUR-              -2 EUR  John Doe----------------------                   0--   One way to show only amounts with a member: value (using a query):--$ hledger balance --pivot member tag:member=.-              -2 EUR  John Doe----------------------              -2 EUR--   Another way (the acct: query matches against the pivoted "account-name"):--$ hledger balance --pivot member acct:.-              -2 EUR  John Doe----------------------              -2 EUR--   Hierarchical reports can be generated with multiple pivots:--$ hledger balance Income:Dues --pivot kind:member-              -2 EUR  Lifetime:John Doe----------------------              -2 EUR---File: hledger.info,  Node: Generating data,  Next: Forecasting,  Prev: Pivoting,  Up: Top--19 Generating data-******************--hledger has several features for generating data, such as:--   * Periodic transaction rules can generate single or repeating-     transactions following a template.  These are usually dated in the-     future, eg to help with forecasting.  They are activated by the-     '--forecast' option.--   * The balance command's '--budget' option uses these same periodic-     rules to generate goals for the budget report.--   * Auto posting rules can generate extra postings on certain matched-     transactions.  They are always applied to forecast transactions;-     with the '--auto' flag they are applied to transactions recorded in-     the journal as well.--   * The '--infer-equity' flag infers missing conversion equity postings-     from @/@@ costs.  And the inverse '--infer-costs' flag infers-     missing @/@@ costs from conversion equity postings.--   Generated data of this kind is temporary, existing only at report-time.  But you can see it in the output of 'hledger print', and you can-save that to your journal, in effect converting it from temporary-generated data to permanent recorded data.  This could be useful as a-data entry aid.--   If you are wondering what data is being generated and why, add the-'--verbose-tags' flag.  In 'hledger print' output you will see extra-tags like 'generated-transaction', 'generated-posting', and 'modified'-on generated/modified data.  Also, even without '--verbose-tags',-generated data always has equivalen hidden tags (with an underscore-prefix), so eg you could match generated transactions with-'tag:_generated-transaction'.---File: hledger.info,  Node: Forecasting,  Next: Budgeting,  Prev: Generating data,  Up: Top--20 Forecasting-**************--Forecasting, or speculative future reporting, can be useful for-estimating future balances, or for exploring different future scenarios.--   The simplest and most flexible way to do it with hledger is to-manually record a bunch of future-dated transactions.  You could keep-these in a separate 'future.journal' and include that with '-f' only-when you want to see them.--* Menu:--* --forecast::-* Inspecting forecast transactions::-* Forecast reports::-* Forecast tags::-* Forecast period in detail::-* Forecast troubleshooting::---File: hledger.info,  Node: --forecast,  Next: Inspecting forecast transactions,  Up: Forecasting--20.1 -forecast-==============--There is another way: with the '--forecast' option, hledger can generate-temporary "forecast transactions" for reporting purposes, according to-periodic transaction rules defined in the journal.  Each rule can-generate multiple recurring transactions, so by changing one rule you-can change many forecasted transactions.  (These same rules can also-generate budget goals, described in Budgeting.)--   Forecast transactions usually start after ordinary transactions end.-By default, they begin after your latest-dated ordinary transaction, or-today, whichever is later, and they end six months from today.  (The-exact rules are a little more complicated, and are given below.)--   This is the "forecast period", which need not be the same as the-report period.  You can override it - eg to forecast farther into the-future, or to force forecast transactions to overlap your ordinary-transactions - by giving the -forecast option a period expression-argument, like '--forecast=..2099' or '--forecast=2023-02-15..'.  Note-that the '=' is required.---File: hledger.info,  Node: Inspecting forecast transactions,  Next: Forecast reports,  Prev: --forecast,  Up: Forecasting--20.2 Inspecting forecast transactions-=====================================--'print' is the best command for inspecting and troubleshooting forecast-transactions.  Eg:--~ monthly from 2022-12-20    rent-    assets:bank:checking-    expenses:rent           $1000--$ hledger print --forecast --today=2023/4/21-2023-05-20 rent-    ; generated-transaction: ~ monthly from 2022-12-20-    assets:bank:checking-    expenses:rent                  $1000--2023-06-20 rent-    ; generated-transaction: ~ monthly from 2022-12-20-    assets:bank:checking-    expenses:rent                  $1000--2023-07-20 rent-    ; generated-transaction: ~ monthly from 2022-12-20-    assets:bank:checking-    expenses:rent                  $1000--2023-08-20 rent-    ; generated-transaction: ~ monthly from 2022-12-20-    assets:bank:checking-    expenses:rent                  $1000--2023-09-20 rent-    ; generated-transaction: ~ monthly from 2022-12-20-    assets:bank:checking-    expenses:rent                  $1000--   Here there are no ordinary transactions, so the forecasted-transactions begin on the first occurence after today's date.  (You-won't normally use '--today'; it's just to make these examples-reproducible.)---File: hledger.info,  Node: Forecast reports,  Next: Forecast tags,  Prev: Inspecting forecast transactions,  Up: Forecasting--20.3 Forecast reports-=====================--Forecast transactions affect all reports, as you would expect.  Eg:--$ hledger areg rent --forecast --today=2023/4/21-Transactions in expenses:rent and subaccounts:-2023-05-20 rent                 as:ba:checking               $1000         $1000-2023-06-20 rent                 as:ba:checking               $1000         $2000-2023-07-20 rent                 as:ba:checking               $1000         $3000-2023-08-20 rent                 as:ba:checking               $1000         $4000-2023-09-20 rent                 as:ba:checking               $1000         $5000--$ hledger bal -M expenses --forecast --today=2023/4/21-Balance changes in 2023-05-01..2023-09-30:--               ||   May    Jun    Jul    Aug    Sep -===============++===================================- expenses:rent || $1000  $1000  $1000  $1000  $1000 ----------------++------------------------------------               || $1000  $1000  $1000  $1000  $1000 ---File: hledger.info,  Node: Forecast tags,  Next: Forecast period in detail,  Prev: Forecast reports,  Up: Forecasting--20.4 Forecast tags-==================--Forecast transactions generated by -forecast have a hidden tag,-'_generated-transaction'.  So if you ever need to match forecast-transactions, you could use 'tag:_generated-transaction' (or just-'tag:generated') in a query.--   For troubleshooting, you can add the '--verbose-tags' flag.  Then,-visible 'generated-transaction' tags will be added also, so you can view-them with the 'print' command.  Their value indicates which periodic-rule was responsible.---File: hledger.info,  Node: Forecast period in detail,  Next: Forecast troubleshooting,  Prev: Forecast tags,  Up: Forecasting--20.5 Forecast period, in detail-===============================--Forecast start/end dates are chosen so as to do something useful by-default in almost all situations, while also being flexible.  Here are-(with luck) the exact rules, to help with troubleshooting:--   The forecast period starts on:--   * the later of-        * the start date in the periodic transaction rule-        * the start date in '--forecast''s argument--   * otherwise (if those are not available): the later of-        * the report start date specified with '-b'/'-p'/'date:'-        * the day after the latest ordinary transaction in the journal--   * otherwise (if none of these are available): today.--   The forecast period ends on:--   * the earlier of-        * the end date in the periodic transaction rule-        * the end date in '--forecast''s argument--   * otherwise: the report end date specified with '-e'/'-p'/'date:'-   * otherwise: 180 days (~6 months) from today.---File: hledger.info,  Node: Forecast troubleshooting,  Prev: Forecast period in detail,  Up: Forecasting--20.6 Forecast troubleshooting-=============================--When -forecast is not doing what you expect, one of these tips should-help:--   * Remember to use the '--forecast' option.-   * Remember to have at least one periodic transaction rule in your-     journal.-   * Test with 'print --forecast'.-   * Check for typos or too-restrictive start/end dates in your periodic-     transaction rule.-   * Leave at least 2 spaces between the rule's period expression and-     description fields.-   * Check for future-dated ordinary transactions suppressing forecasted-     transactions.-   * Try setting explicit report start and/or end dates with '-b', '-e',-     '-p' or 'date:'-   * Try adding the '-E' flag to encourage display of empty periods/zero-     transactions.-   * Try setting explicit forecast start and/or end dates with-     '--forecast=START..END'-   * Consult Forecast period, in detail, above.-   * Check inside the engine: add '--debug=2' (eg).---File: hledger.info,  Node: Budgeting,  Next: Cost reporting,  Prev: Forecasting,  Up: Top--21 Budgeting-************--With the balance command's '--budget' report, each periodic transaction-rule generates recurring budget goals in specified accounts, and goals-and actual performance can be compared.  See the balance command's doc-below.--   You can generate budget goals and forecast transactions at the same-time, from the same or different periodic transaction rules: 'hledger-bal -M --budget --forecast ...'--   See also: Budgeting and Forecasting.---File: hledger.info,  Node: Cost reporting,  Next: Value reporting,  Prev: Budgeting,  Up: Top--22 Cost reporting-*****************--In some transactions - for example a currency conversion, or a purchase-or sale of stock - one commodity is exchanged for another.  In these-transactions there is a conversion rate, also called the cost (when-buying) or selling price (when selling).  In hledger docs we just say-"cost", for convenience; feel free to mentally translate to "conversion-rate" or "selling price" if helpful.--* Menu:--* Recording costs::-* Reporting at cost::-* Equity conversion postings::-* Inferring equity conversion postings::-* Combining costs and equity conversion postings::-* Requirements for detecting equity conversion postings::-* Infer cost and equity by default ?::---File: hledger.info,  Node: Recording costs,  Next: Reporting at cost,  Up: Cost reporting--22.1 Recording costs-====================--We'll explore several ways of recording transactions involving costs.-These are also summarised at hledger Cookbook > Cost notation.--   Costs can be recorded explicitly in the journal, using the '@-UNITCOST' or '@@ TOTALCOST' notation described in Journal > Costs:--   *Variant 1*--2022-01-01-  assets:dollars    $-135-  assets:euros       €100 @ $1.35   ; $1.35 per euro (unit cost)--   *Variant 2*--2022-01-01-  assets:dollars    $-135-  assets:euros       €100 @@ $135   ; $135 total cost--   Typically, writing the unit cost (variant 1) is preferable; it can be-more effort, requiring more attention to decimal digits; but it reveals-the per-unit cost basis, and makes stock sales easier.--   Costs can also be left implicit, and hledger will infer the cost that-is consistent with a balanced transaction:--   *Variant 3*--2022-01-01-  assets:dollars    $-135-  assets:euros       €100--   Here, hledger will attach a '@@ €100' cost to the first amount (you-can see it with 'hledger print -x').  This form looks convenient, but-there are downsides:--   * It sacrifices some error checking.  For example, if you-     accidentally wrote €10 instead of €100, hledger would not be able-     to detect the mistake.--   * It is sensitive to the order of postings - if they were reversed, a-     different entry would be inferred and reports would be different.--   * The per-unit cost basis is not easy to read.--   So generally this kind of entry is not recommended.  You can make-sure you have none of these by using '-s' (strict mode), or by running-'hledger check balanced'.---File: hledger.info,  Node: Reporting at cost,  Next: Equity conversion postings,  Prev: Recording costs,  Up: Cost reporting--22.2 Reporting at cost-======================--Now when you add the '-B'/'--cost' flag to reports ("B" is from Ledger's--B/-basis/-cost flag), any amounts which have been annotated with costs-will be converted to their cost's commodity (in the report output).  Ie-they will be displayed "at cost" or "at sale price".--   Some things to note:--   * Costs are attached to specific posting amounts in specific-     transactions, and once recorded they do not change.  This contrasts-     with market prices, which are ambient and fluctuating.--   * Conversion to cost is performed before conversion to market value-     (described below).---File: hledger.info,  Node: Equity conversion postings,  Next: Inferring equity conversion postings,  Prev: Reporting at cost,  Up: Cost reporting--22.3 Equity conversion postings-===============================--There is a problem with the entries above - they are not conventional-Double Entry Bookkeeping (DEB) notation, and because of the "magical"-transformation of one commodity into another, they cause an imbalance in-the Accounting Equation.  This shows up as a non-zero grand total in-balance reports like 'hledger bse'.--   For most hledger users, this doesn't matter in practice and can-safely be ignored !  But if you'd like to learn more, keep reading.--   Conventional DEB uses an extra pair of equity postings to balance the-transaction.  Of course you can do this in hledger as well:--   *Variant 4*--2022-01-01-    assets:dollars      $-135-    assets:euros         €100-    equity:conversion    $135-    equity:conversion   €-100--   Now the transaction is perfectly balanced according to standard DEB,-and 'hledger bse''s total will not be disrupted.--   And, hledger can still infer the cost for cost reporting, but it's-not done by default - you must add the '--infer-costs' flag like so:--$ hledger print --infer-costs-2022-01-01 one hundred euros purchased at $1.35 each-    assets:dollars       $-135 @@ €100-    assets:euros                  €100-    equity:conversion             $135-    equity:conversion            €-100--$ hledger bal --infer-costs -B-               €-100  assets:dollars                                                                                                                                              -                €100  assets:euros                                                                                                                                                ---------------------                                                                                                                                                              -                   0                                                                                                                                                              --   Here are some downsides of this kind of entry:--   * The per-unit cost basis is not easy to read.--   * Instead of '-B' you must remember to type '-B --infer-costs'.--   * '--infer-costs' works only where hledger can identify the two-     equity:conversion postings and match them up with the two-     non-equity postings.  So writing the journal entry in a particular-     format becomes more important.  More on this below.---File: hledger.info,  Node: Inferring equity conversion postings,  Next: Combining costs and equity conversion postings,  Prev: Equity conversion postings,  Up: Cost reporting--22.4 Inferring equity conversion postings-=========================================--Can we go in the other direction ?  Yes, if you have transactions-written with the @/@@ cost notation, hledger can infer the missing-equity postings, if you add the '--infer-equity' flag.  Eg:--2022-01-01-  assets:dollars  -$135-  assets:euros     €100 @ $1.35--$ hledger print --infer-equity-2022-01-01-    assets:dollars                    $-135-    assets:euros               €100 @ $1.35-    equity:conversion:$-€:€           €-100-    equity:conversion:$-€:$         $135.00--   The equity account names will be "equity:conversion:A-B:A" and-"equity:conversion:A-B:B" where A is the alphabetically first commodity-symbol.  You can customise the "equity:conversion" part by declaring an-account with the 'V'/'Conversion' account type.---File: hledger.info,  Node: Combining costs and equity conversion postings,  Next: Requirements for detecting equity conversion postings,  Prev: Inferring equity conversion postings,  Up: Cost reporting--22.5 Combining costs and equity conversion postings-===================================================--Finally, you can use both the @/@@ cost notation and equity postings at-the same time.  This in theory gives the best of all worlds - preserving-the accounting equation, revealing the per-unit cost basis, and-providing more flexibility in how you write the entry:--   *Variant 5*--2022-01-01 one hundred euros purchased at $1.35 each-    assets:dollars      $-135-    equity:conversion    $135-    equity:conversion   €-100-    assets:euros         €100 @ $1.35--   All the other variants above can (usually) be rewritten to this final-form with:--$ hledger print -x --infer-costs --infer-equity--   Downsides:--   * This was added in hledger-1.29 and is still somewhat experimental.--   * The precise format of the journal entry becomes more important.  If-     hledger can't detect and match up the cost and equity postings, it-     will give a transaction balancing error.--   * The add command does not yet accept this kind of entry (#2056).--   * This is the most verbose form.---File: hledger.info,  Node: Requirements for detecting equity conversion postings,  Next: Infer cost and equity by default ?,  Prev: Combining costs and equity conversion postings,  Up: Cost reporting--22.6 Requirements for detecting equity conversion postings-==========================================================--'--infer-costs' has certain requirements (unlike '--infer-equity', which-always works).  It will infer costs only in transactions with:--   * Two non-equity postings, in different commodities.  Their order is-     significant: the cost will be added to the first of them.--   * Two postings to equity conversion accounts, next to one another,-     which balance the two non-equity postings.  This balancing is-     checked to the same precision (number of decimal places) used in-     the conversion posting's amount.  Equity conversion accounts are:--        * any accounts declared with account type 'V'/'Conversion', or-          their subaccounts-        * otherwise, accounts named 'equity:conversion', 'equity:trade',-          or 'equity:trading', or their subaccounts.--   And multiple such four-posting groups can coexist within a single-transaction.  When '--infer-costs' fails, it does not infer a cost in-that transaction, and does not raise an error (ie, it infers costs where-it can).--   Reading variant 5 journal entries, combining cost notation and equity-postings, has all the same requirements.  When reading such an entry-fails, hledger raises an "unbalanced transaction" error.---File: hledger.info,  Node: Infer cost and equity by default ?,  Prev: Requirements for detecting equity conversion postings,  Up: Cost reporting--22.7 Infer cost and equity by default ?-=======================================--Should '--infer-costs' and '--infer-equity' be enabled by default ?  Try-using them always, eg with a shell alias:--alias h="hledger --infer-equity --infer-costs"--   and let us know what problems you find.---File: hledger.info,  Node: Value reporting,  Next: PART 4 COMMANDS,  Prev: Cost reporting,  Up: Top--23 Value reporting-******************--Instead of reporting amounts in their original commodity, hledger can-convert them to cost/sale amount (using the conversion rate recorded in-the transaction), and/or to market value (using some market price on a-certain date).  This is controlled by the '--value=TYPE[,COMMODITY]'-option, which will be described below.  We also provide the simpler '-V'-and '-X COMMODITY' options, and often one of these is all you need:--* Menu:--* -V Value::-* -X Value in specified commodity::-* Valuation date::-* Finding market price::-* --infer-market-prices market prices from transactions::-* Valuation commodity::-* Simple valuation examples::-* --value Flexible valuation::-* More valuation examples::-* Interaction of valuation and queries::-* Effect of valuation on reports::---File: hledger.info,  Node: -V Value,  Next: -X Value in specified commodity,  Up: Value reporting--23.1 -V: Value-==============--The '-V/--market' flag converts amounts to market value in their default-_valuation commodity_, using the market prices in effect on the-_valuation date(s)_, if any.  More on these in a minute.---File: hledger.info,  Node: -X Value in specified commodity,  Next: Valuation date,  Prev: -V Value,  Up: Value reporting--23.2 -X: Value in specified commodity-=====================================--The '-X/--exchange=COMM' option is like '-V', except you tell it which-currency you want to convert to, and it tries to convert everything to-that.---File: hledger.info,  Node: Valuation date,  Next: Finding market price,  Prev: -X Value in specified commodity,  Up: Value reporting--23.3 Valuation date-===================--Market prices can change from day to day.  hledger will use the prices-on a particular valuation date (or on more than one date).  By default-hledger uses "end" dates for valuation.  More specifically:--   * For single period reports (including normal print and register-     reports):-        * If an explicit report end date is specified, that is used-        * Otherwise the latest transaction date or P directive date is-          used (even if it's in the future)--   * For multiperiod reports, each period is valued on its last day.--   This can be customised with the -value option described below, which-can select either "then", "end", "now", or "custom" dates.  (Note, this-has a bug in hledger-ui <=1.31: turning on valuation with the 'V' key-always resets it to "end".)---File: hledger.info,  Node: Finding market price,  Next: --infer-market-prices market prices from transactions,  Prev: Valuation date,  Up: Value reporting--23.4 Finding market price-=========================--To convert a commodity A to its market value in another commodity B,-hledger looks for a suitable market price (exchange rate) as follows, in-this order of preference:--  1. A _declared market price_ or _inferred market price_: A's latest-     market price in B on or before the valuation date as declared by a-     P directive, or (with the '--infer-market-prices' flag) inferred-     from costs.--  2. A _reverse market price_: the inverse of a declared or inferred-     market price from B to A.--  3. A _forward chain of market prices_: a synthetic price formed by-     combining the shortest chain of "forward" (only 1 above) market-     prices, leading from A to B.--  4. _Any chain of market prices_: a chain of any market prices,-     including both forward and reverse prices (1 and 2 above), leading-     from A to B.--   There is a limit to the length of these price chains; if hledger-reaches that length without finding a complete chain or exhausting all-possibilities, it will give up (with a "gave up" message visible in-'--debug=2' output).  That limit is currently 1000.--   Amounts for which no suitable market price can be found, are not-converted.---File: hledger.info,  Node: --infer-market-prices market prices from transactions,  Next: Valuation commodity,  Prev: Finding market price,  Up: Value reporting--23.5 -infer-market-prices: market prices from transactions-==========================================================--Normally, market value in hledger is fully controlled by, and requires,-P directives in your journal.  Since adding and updating those can be a-chore, and since transactions usually take place at close to market-value, why not use the recorded costs as additional market prices (as-Ledger does) ?  Adding the '--infer-market-prices' flag to '-V', '-X' or-'--value' enables this.--   So for example, 'hledger bs -V --infer-market-prices' will get market-prices both from P directives and from transactions.  If both occur on-the same day, the P directive takes precedence.--   There is a downside: value reports can sometimes be affected in-confusing/undesired ways by your journal entries.  If this happens to-you, read all of this Value reporting section carefully, and try adding-'--debug' or '--debug=2' to troubleshoot.--   '--infer-market-prices' can infer market prices from:--   * multicommodity transactions with explicit prices ('@'/'@@')--   * multicommodity transactions with implicit prices (no '@', two-     commodities, unbalanced).  (With these, the order of postings-     matters.  'hledger print -x' can be useful for troubleshooting.)--   * multicommodity transactions with equity postings, if cost is-     inferred with '--infer-costs'.--   There is a limitation (bug) currently: when a valuation commodity is-not specified, prices inferred with '--infer-market-prices' do not help-select a default valuation commodity, as 'P' prices would.  So-conversion might not happen because no valuation commodity was detected-('--debug=2' will show this).  To be safe, specify the valuation-commmodity, eg:--   * '-X EUR --infer-market-prices', not '-V --infer-market-prices'-   * '--value=then,EUR --infer-market-prices', not '--value=then-     --infer-market-prices'--   Signed costs and market prices can be confusing.  For reference, here-is the current behaviour, since hledger 1.25.  (If you think it should-work differently, see #1870.)--2022-01-01 Positive Unit prices-    a        A 1-    b        B -1 @ A 1--2022-01-01 Positive Total prices-    a        A 1-    b        B -1 @@ A 1---2022-01-02 Negative unit prices-    a        A 1-    b        B 1 @ A -1--2022-01-02 Negative total prices-    a        A 1-    b        B 1 @@ A -1---2022-01-03 Double Negative unit prices-    a        A -1-    b        B -1 @ A -1--2022-01-03 Double Negative total prices-    a        A -1-    b        B -1 @@ A -1--   All of the transactions above are considered balanced (and on each-day, the two transactions are considered equivalent).  Here are the-market prices inferred for B:--$ hledger -f- --infer-market-prices prices-P 2022-01-01 B A 1-P 2022-01-01 B A 1.0-P 2022-01-02 B A -1-P 2022-01-02 B A -1.0-P 2022-01-03 B A -1-P 2022-01-03 B A -1.0---File: hledger.info,  Node: Valuation commodity,  Next: Simple valuation examples,  Prev: --infer-market-prices market prices from transactions,  Up: Value reporting--23.6 Valuation commodity-========================--*When you specify a valuation commodity ('-X COMM' or '--value-TYPE,COMM'):*-hledger will convert all amounts to COMM, wherever it can find a-suitable market price (including by reversing or chaining prices).--   *When you leave the valuation commodity unspecified ('-V' or '--value-TYPE'):*-For each commodity A, hledger picks a default valuation commodity as-follows, in this order of preference:--  1. The price commodity from the latest P-declared market price for A-     on or before valuation date.--  2. The price commodity from the latest P-declared market price for A-     on any date.  (Allows conversion to proceed when there are inferred-     prices before the valuation date.)--  3. If there are no P directives at all (any commodity or date) and the-     '--infer-market-prices' flag is used: the price commodity from the-     latest transaction-inferred price for A on or before valuation-     date.--   This means:--   * If you have P directives, they determine which commodities '-V'-     will convert, and to what.--   * If you have no P directives, and use the '--infer-market-prices'-     flag, costs determine it.--   Amounts for which no valuation commodity can be found are not-converted.---File: hledger.info,  Node: Simple valuation examples,  Next: --value Flexible valuation,  Prev: Valuation commodity,  Up: Value reporting--23.7 Simple valuation examples-==============================--Here are some quick examples of '-V':--; one euro is worth this many dollars from nov 1-P 2016/11/01 € $1.10--; purchase some euros on nov 3-2016/11/3-    assets:euros        €100-    assets:checking--; the euro is worth fewer dollars by dec 21-P 2016/12/21 € $1.03--   How many euros do I have ?--$ hledger -f t.j bal -N euros-                €100  assets:euros--   What are they worth at end of nov 3 ?--$ hledger -f t.j bal -N euros -V -e 2016/11/4-             $110.00  assets:euros--   What are they worth after 2016/12/21 ?  (no report end date-specified, defaults to today)--$ hledger -f t.j bal -N euros -V-             $103.00  assets:euros---File: hledger.info,  Node: --value Flexible valuation,  Next: More valuation examples,  Prev: Simple valuation examples,  Up: Value reporting--23.8 -value: Flexible valuation-===============================--'-V' and '-X' are special cases of the more general '--value' option:-- --value=TYPE[,COMM]  TYPE is then, end, now or YYYY-MM-DD.-                      COMM is an optional commodity symbol.-                      Shows amounts converted to:-                      - default valuation commodity (or COMM) using market prices at posting dates-                      - default valuation commodity (or COMM) using market prices at period end(s)-                      - default valuation commodity (or COMM) using current market prices-                      - default valuation commodity (or COMM) using market prices at some date--   The TYPE part selects cost or value and valuation date:--'--value=then'--     Convert amounts to their value in the default valuation commodity,-     using market prices on each posting's date.-'--value=end'--     Convert amounts to their value in the default valuation commodity,-     using market prices on the last day of the report period (or if-     unspecified, the journal's end date); or in multiperiod reports,-     market prices on the last day of each subperiod.-'--value=now'--     Convert amounts to their value in the default valuation commodity-     using current market prices (as of when report is generated).-'--value=YYYY-MM-DD'--     Convert amounts to their value in the default valuation commodity-     using market prices on this date.--   To select a different valuation commodity, add the optional ',COMM'-part: a comma, then the target commodity's symbol.  Eg:-*'--value=now,EUR'*.  hledger will do its best to convert amounts to-this commodity, deducing market prices as described above.---File: hledger.info,  Node: More valuation examples,  Next: Interaction of valuation and queries,  Prev: --value Flexible valuation,  Up: Value reporting--23.9 More valuation examples-============================--Here are some examples showing the effect of '--value', as seen with-'print':--P 2000-01-01 A  1 B-P 2000-02-01 A  2 B-P 2000-03-01 A  3 B-P 2000-04-01 A  4 B--2000-01-01-  (a)      1 A @ 5 B--2000-02-01-  (a)      1 A @ 6 B--2000-03-01-  (a)      1 A @ 7 B--   Show the cost of each posting:--$ hledger -f- print --cost-2000-01-01-    (a)             5 B--2000-02-01-    (a)             6 B--2000-03-01-    (a)             7 B--   Show the value as of the last day of the report period (2000-02-29):--$ hledger -f- print --value=end date:2000/01-2000/03-2000-01-01-    (a)             2 B--2000-02-01-    (a)             2 B--   With no report period specified, that shows the value as of the last-day of the journal (2000-03-01):--$ hledger -f- print --value=end-2000-01-01-    (a)             3 B--2000-02-01-    (a)             3 B--2000-03-01-    (a)             3 B--   Show the current value (the 2000-04-01 price is still in effect-today):--$ hledger -f- print --value=now-2000-01-01-    (a)             4 B--2000-02-01-    (a)             4 B--2000-03-01-    (a)             4 B--   Show the value on 2000/01/15:--$ hledger -f- print --value=2000-01-15-2000-01-01-    (a)             1 B--2000-02-01-    (a)             1 B--2000-03-01-    (a)             1 B---File: hledger.info,  Node: Interaction of valuation and queries,  Next: Effect of valuation on reports,  Prev: More valuation examples,  Up: Value reporting--23.10 Interaction of valuation and queries-==========================================--When matching postings based on queries in the presence of valuation,-the following happens.--  1. The query is separated into two parts:-       1. the currency ('cur:') or amount ('amt:').-       2. all other parts.--  2. The postings are matched to the currency and amount queries based-     on pre-valued amounts.-  3. Valuation is applied to the postings.-  4. The postings are matched to the other parts of the query based on-     post-valued amounts.--   See: 1625---File: hledger.info,  Node: Effect of valuation on reports,  Prev: Interaction of valuation and queries,  Up: Value reporting--23.11 Effect of valuation on reports-====================================--Here is a reference for how valuation is supposed to affect each part of-hledger's reports (and a glossary).  (It's wide, you'll have to scroll-sideways.)  It may be useful when troubleshooting.  If you find-problems, please report them, ideally with a reproducible example.-Related: #329, #1083.--Report     '-B',        '-V', '-X'   '--value=then'     '--value=end''--value=DATE',-type       '--cost'                                                  '--value=now'--------------------------------------------------------------------------------*print*-posting    cost         value at     value at posting   value at     value-amounts                 report end   date               report or    at-                        or today                        journal      DATE/today-                                                        end-balance    unchanged    unchanged    unchanged          unchanged    unchanged-assertions/assignments-*register*-starting   cost         value at     valued at day      value at     value-balance                 report or    each historical    report or    at-(-H)                    journal      posting was made   journal      DATE/today-                        end                             end-starting   cost         value at     valued at day      value at     value-balance                 day before   each historical    day before   at-(-H)                    report or    posting was made   report or    DATE/today-with                    journal                         journal-report                  start                           start-interval-posting    cost         value at     value at posting   value at     value-amounts                 report or    date               report or    at-                        journal                         journal      DATE/today-                        end                             end-summary    summarised   value at     sum of postings    value at     value-posting    cost         period       in interval,       period       at-amounts                 ends         valued at          ends         DATE/today-with                                 interval start-report-interval-running    sum/average  sum/average  sum/average of     sum/average  sum/average-total/averageof         of           displayed values   of           of-           displayed    displayed                       displayed    displayed-           values       values                          values       values-*balance-(bs,-bse, cf,-is)*-balance    sums of      value at     value at posting   value at     value-changes    costs        report end   date               report or    at-                        or today                        journal      DATE/today-                        of sums of                      end of       of-                        postings                        sums of      sums-                                                        postings     of-                                                                     postings-budget     like         like         like balance       like         like-amounts    balance      balance      changes            balances     balance-(-budget)  changes      changes                                      changes-grand      sum of       sum of       sum of displayed   sum of       sum of-total      displayed    displayed    valued             displayed    displayed-           values       values                          values       values-*balance-(bs,-bse, cf,-is) with-report-interval*-starting   sums of      value at     sums of values     value at     sums-balances   costs of     report       of postings        report       of-(-H)       postings     start of     before report      start of     postings-           before       sums of      start at           sums of      before-           report       all          respective         all          report-           start        postings     posting dates      postings     start-                        before                          before-                        report                          report-                        start                           start-balance    sums of      same as      sums of values     balance      value-changes    costs of     -value=end   of postings in     change in    at-(bal,      postings                  period at          each         DATE/today-is, bs     in period                 respective         period,      of--change,                             posting dates      valued at    sums-cf                                                      period       of--change)                                                ends         postings-end        sums of      same as      sums of values     period end   value-balances   costs of     -value=end   of postings from   balances,    at-(bal -H,   postings                  before period      valued at    DATE/today-is -H,     from                      start to period    period       of-bs, cf)    before                    end at             ends         sums-           report                    respective                      of-           start to                  posting dates                   postings-           period end-budget     like         like         like balance       like         like-amounts    balance      balance      changes/end        balances     balance-(-budget)  changes/end  changes/end  balances                        changes/end-           balances     balances                                     balances-row        sums,        sums,        sums, averages     sums,        sums,-totals,    averages     averages     of displayed       averages     averages-row        of           of           values             of           of-averages   displayed    displayed                       displayed    displayed-(-T, -A)   values       values                          values       values-column     sums of      sums of      sums of            sums of      sums-totals     displayed    displayed    displayed values   displayed    of-           values       values                          values       displayed-                                                                     values-grand      sum,         sum,         sum, average of    sum,         sum,-total,     average of   average of   column totals      average of   average-grand      column       column                          column       of-average    totals       totals                          totals       column-                                                                     totals--   '--cumulative' is omitted to save space, it works like '-H' but with-a zero starting balance.--   *Glossary:*--_cost_--     calculated using price(s) recorded in the transaction(s).-_value_--     market value using available market price declarations, or the-     unchanged amount if no conversion rate can be found.-_report start_--     the first day of the report period specified with -b or -p or-     date:, otherwise today.-_report or journal start_--     the first day of the report period specified with -b or -p or-     date:, otherwise the earliest transaction date in the journal,-     otherwise today.-_report end_--     the last day of the report period specified with -e or -p or date:,-     otherwise today.-_report or journal end_--     the last day of the report period specified with -e or -p or date:,-     otherwise the latest transaction date in the journal, otherwise-     today.-_report interval_--     a flag (-D/-W/-M/-Q/-Y) or period expression that activates the-     report's multi-period mode (whether showing one or many-     subperiods).---File: hledger.info,  Node: PART 4 COMMANDS,  Next: PART 5 COMMON TASKS,  Prev: Value reporting,  Up: Top--24 PART 4: COMMANDS-*******************--* Menu:--* Commands overview::-* accounts::-* activity::-* add::-* aregister::-* balance::-* balancesheet::-* balancesheetequity::-* cashflow::-* check::-* close::-* codes::-* commodities::-* demo::-* descriptions::-* diff::-* files::-* help::-* import::-* incomestatement::-* notes::-* payees::-* prices::-* print::-* register::-* rewrite::-* roi::-* stats::-* tags::-* test::---File: hledger.info,  Node: Commands overview,  Next: accounts,  Up: PART 4 COMMANDS--24.1 Commands overview-======================--Here are the built-in commands:--* Menu:--* DATA ENTRY::-* DATA CREATION::-* DATA MANAGEMENT::-* REPORTS FINANCIAL::-* REPORTS VERSATILE::-* REPORTS BASIC::-* HELP::-* ADD-ONS::---File: hledger.info,  Node: DATA ENTRY,  Next: DATA CREATION,  Up: Commands overview--24.1.1 DATA ENTRY--------------------These data entry commands are the only ones which can modify your-journal file.--   * add - add transactions using terminal prompts-   * import - add new transactions from other files, eg CSV files---File: hledger.info,  Node: DATA CREATION,  Next: DATA MANAGEMENT,  Prev: DATA ENTRY,  Up: Commands overview--24.1.2 DATA CREATION-----------------------   * close - generate balance-zeroing/restoring transactions-   * rewrite - generate auto postings, like print -auto---File: hledger.info,  Node: DATA MANAGEMENT,  Next: REPORTS FINANCIAL,  Prev: DATA CREATION,  Up: Commands overview--24.1.3 DATA MANAGEMENT-------------------------   * check - check for various kinds of error in the data-   * diff - compare account transactions in two journal files---File: hledger.info,  Node: REPORTS FINANCIAL,  Next: REPORTS VERSATILE,  Prev: DATA MANAGEMENT,  Up: Commands overview--24.1.4 REPORTS, FINANCIAL----------------------------   * aregister (areg) - show transactions in a particular account-   * balancesheet (bs) - show assets, liabilities and net worth-   * balancesheetequity (bse) - show assets, liabilities and equity-   * cashflow (cf) - show changes in liquid assets-   * incomestatement (is) - show revenues and expenses---File: hledger.info,  Node: REPORTS VERSATILE,  Next: REPORTS BASIC,  Prev: REPORTS FINANCIAL,  Up: Commands overview--24.1.5 REPORTS, VERSATILE----------------------------   * balance (bal) - show balance changes, end balances, budgets,-     gains..-   * print - show transactions or export journal data-   * register (reg) - show postings in one or more accounts & running-     total-   * roi - show return on investments---File: hledger.info,  Node: REPORTS BASIC,  Next: HELP,  Prev: REPORTS VERSATILE,  Up: Commands overview--24.1.6 REPORTS, BASIC------------------------   * accounts - show account names-   * activity - show bar charts of posting counts per period-   * codes - show transaction codes-   * commodities - show commodity/currency symbols-   * descriptions - show transaction descriptions-   * files - show input file paths-   * notes - show note parts of transaction descriptions-   * payees - show payee parts of transaction descriptions-   * prices - show market prices-   * stats - show journal statistics-   * tags - show tag names-   * test - run self tests---File: hledger.info,  Node: HELP,  Next: ADD-ONS,  Prev: REPORTS BASIC,  Up: Commands overview--24.1.7 HELP--------------   * help - show the hledger manual with info/man/pager-   * demo - show small hledger demos in the terminal---File: hledger.info,  Node: ADD-ONS,  Prev: HELP,  Up: Commands overview--24.1.8 ADD-ONS-----------------And here are some typical add-on commands.  Some of these are installed-by the hledger-install script.  If installed, they will appear in-hledger's commands list:--   * ui - run hledger's terminal UI-   * web - run hledger's web UI-   * iadd - add transactions using a TUI (currently hard to build)-   * interest - generate interest transactions-   * stockquotes - download market prices from AlphaVantage-   * Scripts and add-ons - check-fancyassertions, edit, fifo, git, move,-     pijul, plot, and more..--   Next, each command is described in detail, in alphabetical order.---File: hledger.info,  Node: accounts,  Next: activity,  Prev: Commands overview,  Up: PART 4 COMMANDS--24.2 accounts-=============--Show account names.--   This command lists account names.  By default it shows all known-accounts, either used in transactions or declared with account-directives.--   With query arguments, only matched account names and account names-referenced by matched postings are shown.--   Or it can show just the used accounts ('--used'/'-u'), the declared-accounts ('--declared'/'-d'), the accounts declared but not used-('--unused'), the accounts used but not declared ('--undeclared'), or-the first account matched by an account name pattern, if any ('--find').--   It shows a flat list by default.  With '--tree', it uses indentation-to show the account hierarchy.  In flat mode you can add '--drop N' to-omit the first few account name components.  Account names can be-depth-clipped with 'depth:N' or '--depth N' or '-N'.--   With '--types', it also shows each account's type, if it's known.-(See Declaring accounts > Account types.)--   With '--positions', it also shows the file and line number of each-account's declaration, if any, and the account's overall declaration-order; these may be useful when troubleshooting account display order.--   With '--directives', it adds the 'account' keyword, showing valid-account directives which can be pasted into a journal file.  This is-useful together with '--undeclared' when updating your account-declarations to satisfy 'hledger check accounts'.--   The '--find' flag can be used to look up a single account name, in-the same way that the 'aregister' command does.  It returns the-alphanumerically-first matched account name, or if none can be found, it-fails with a non-zero exit code.--   Examples:--$ hledger accounts-assets:bank:checking-assets:bank:saving-assets:cash-expenses:food-expenses:supplies-income:gifts-income:salary-liabilities:debts--$ hledger accounts --undeclared --directives >> $LEDGER_FILE-$ hledger check accounts---File: hledger.info,  Node: activity,  Next: add,  Prev: accounts,  Up: PART 4 COMMANDS--24.3 activity-=============--Show an ascii barchart of posting counts per interval.--   The activity command displays an ascii histogram showing transaction-counts by day, week, month or other reporting interval (by day is the-default).  With query arguments, it counts only matched transactions.--   Examples:--$ hledger activity --quarterly-2008-01-01 **-2008-04-01 *******-2008-07-01 -2008-10-01 **---File: hledger.info,  Node: add,  Next: aregister,  Prev: activity,  Up: PART 4 COMMANDS--24.4 add-========--Prompt for transactions and add them to the journal.  Any arguments will-be used as default inputs for the first N prompts.--   Many hledger users edit their journals directly with a text editor,-or generate them from CSV. For more interactive data entry, there is the-'add' command, which prompts interactively on the console for new-transactions, and appends them to the main journal file (which should be-in journal format).  Existing transactions are not changed.  This is one-of the few hledger commands that writes to the journal file (see also-'import').--   To use it, just run 'hledger add' and follow the prompts.  You can-add as many transactions as you like; when you are finished, enter '.'-or press control-d or control-c to exit.--   Features:--   * add tries to provide useful defaults, using the most similar (by-     description) recent transaction (filtered by the query, if any) as-     a template.-   * You can also set the initial defaults with command line arguments.-   * Readline-style edit keys can be used during data entry.-   * The tab key will auto-complete whenever possible - accounts,-     payees/descriptions, dates ('yesterday', 'today', 'tomorrow').  If-     the input area is empty, it will insert the default value.-   * If the journal defines a default commodity, it will be added to any-     bare numbers entered.-   * A parenthesised transaction code may be entered following a date.-   * Comments and tags may be entered following a description or amount.-   * If you make a mistake, enter '<' at any prompt to go one step-     backward.-   * Input prompts are displayed in a different colour when the terminal-     supports it.--   Example (see https://hledger.org/add.html for a detailed tutorial):--$ hledger add-Adding transactions to journal file /src/hledger/examples/sample.journal-Any command line arguments will be used as defaults.-Use tab key to complete, readline keys to edit, enter to accept defaults.-An optional (CODE) may follow transaction dates.-An optional ; COMMENT may follow descriptions or amounts.-If you make a mistake, enter < at any prompt to go one step backward.-To end a transaction, enter . when prompted.-To quit, enter . at a date prompt or press control-d or control-c.-Date [2015/05/22]: -Description: supermarket-Account 1: expenses:food-Amount  1: $10-Account 2: assets:checking-Amount  2 [$-10.0]: -Account 3 (or . or enter to finish this transaction): .-2015/05/22 supermarket-    expenses:food             $10-    assets:checking        $-10.0--Save this transaction to the journal ? [y]: -Saved.-Starting the next transaction (. or ctrl-D/ctrl-C to quit)-Date [2015/05/22]: <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: PART 4 COMMANDS--24.5 aregister-==============--(areg)--   Show the transactions and running historical balance of a single-account, with each transaction displayed as one line.--   'aregister' shows the overall transactions affecting a particular-account (and any subaccounts).  Each report line represents one-transaction in this account.  Transactions before the report start date-are always included in the running balance ('--historical' mode is-always on).--   This is a more "real world", bank-like view than the 'register'-command (which shows individual postings, possibly from multiple-accounts, not necessarily in historical mode).  As a quick rule of-thumb: - use 'aregister' for reviewing and reconciling real-world-asset/liability accounts - use 'register' for reviewing detailed-revenues/expenses.--   'aregister' requires one argument: the account to report on.  You can-write either the full account name, or a case-insensitive regular-expression which will select the alphabetically first matched account.--   When there are multiple matches, the alphabetically-first choice can-be surprising; eg if you have 'assets:per:checking 1' and-'assets:biz:checking 2' accounts, 'hledger areg checking' would select-'assets:biz:checking 2'.  It's just a convenience to save typing, so if-in doubt, write the full account name, or a distinctive substring that-matches uniquely.--   Transactions involving subaccounts of this account will also be-shown.  'aregister' ignores depth limits, so its final total will always-match a balance report with similar arguments.--   Any additional arguments form a query which will filter the-transactions shown.  Note some queries will disturb the running balance,-causing it to be different from the account's real-world running-balance.--   An example: this shows the transactions and historical running-balance during july, in the first account whose name contains-"checking":--$ hledger areg checking date:jul--   Each 'aregister' line item shows:--   * the transaction's date (or the relevant posting's date if-     different, see below)-   * the names of all the other account(s) involved in this transaction-     (probably abbreviated)-   * the total change to this account's balance from this transaction-   * the account's historical running balance after this transaction.--   Transactions making a net change of zero are not shown by default;-add the '-E/--empty' flag to show them.--   For performance reasons, column widths are chosen based on the first-1000 lines; this means unusually wide values in later lines can cause-visual discontinuities as column widths are adjusted.  If you want to-ensure perfect alignment, at the cost of more time and memory, use the-'--align-all' flag.--   This command also supports the output destination and output format-options.  The output formats supported are 'txt', 'csv', 'tsv', and-'json'.--* Menu:--* aregister and posting dates::---File: hledger.info,  Node: aregister and posting dates,  Up: aregister--24.5.1 aregister and posting dates-------------------------------------aregister always shows one line (and date and amount) per transaction.-But sometimes transactions have postings with different dates.  Also,-not all of a transaction's postings may be within the report period.  To-resolve this, aregister shows the earliest of the transaction's date and-posting dates that is in-period, and the sum of the in-period postings.-In other words it will show a combined line item with just the earliest-date, and the running balance will (temporarily, until the transaction's-last posting) be inaccurate.  Use 'register -H' if you need to see the-individual postings.--   There is also a '--txn-dates' flag, which filters strictly by-transaction date, ignoring posting dates.  This too can cause an-inaccurate running balance.---File: hledger.info,  Node: balance,  Next: balancesheet,  Prev: aregister,  Up: PART 4 COMMANDS--24.6 balance-============--(bal)--   Show accounts and their balances.--   'balance' is one of hledger's oldest and most versatile commands, for-listing account balances, balance changes, values, value changes and-more, during one time period or many.  Generally it shows a table, with-rows representing accounts, and columns representing periods.--   Note there are some higher-level variants of the 'balance' command-with convenient defaults, which can be simpler to use: 'balancesheet',-'balancesheetequity', 'cashflow' and 'incomestatement'.  When you need-more control, then use 'balance'.--* Menu:--* balance features::-* Simple balance report::-* Balance report line format::-* Filtered balance report::-* List or tree mode::-* Depth limiting::-* Dropping top-level accounts::-* Showing declared accounts::-* Sorting by amount::-* Percentages::-* Multi-period balance report::-* Balance change end balance::-* Balance report types::-* Budget report::-* Balance report layout::-* Useful balance reports::---File: hledger.info,  Node: balance features,  Next: Simple balance report,  Up: balance--24.6.1 balance features--------------------------Here's a quick overview of the 'balance' command's features, followed by-more detailed descriptions and examples.  Many of these work with the-higher-level commands as well.--   'balance' can show..--   * accounts as a list ('-l') or a tree ('-t')-   * optionally depth-limited ('-[1-9]')-   * sorted by declaration order and name, or by amount--   ..and their..--   * balance changes (the default)-   * or actual and planned balance changes ('--budget')-   * or value of balance changes ('-V')-   * or change of balance values ('--valuechange')-   * or unrealised capital gain/loss ('--gain')-   * or postings count ('--count')--   ..in..--   * one time period (the whole journal period by default)-   * or multiple periods ('-D', '-W', '-M', '-Q', '-Y', '-p INTERVAL')--   ..either..--   * per period (the default)-   * or accumulated since report start date ('--cumulative')-   * or accumulated since account creation ('--historical/-H')--   ..possibly converted to..--   * cost ('--value=cost[,COMM]'/'--cost'/'-B')-   * or market value, as of transaction dates ('--value=then[,COMM]')-   * or at period ends ('--value=end[,COMM]')-   * or now ('--value=now')-   * or at some other date ('--value=YYYY-MM-DD')--   ..with..--   * totals ('-T'), averages ('-A'), percentages ('-%'), inverted sign-     ('--invert')-   * rows and columns swapped ('--transpose')-   * another field used as account name ('--pivot')-   * custom-formatted line items (single-period reports only)-     ('--format')-   * commodities displayed on the same line or multiple lines-     ('--layout')--   This command supports the output destination and output format-options, with output formats 'txt', 'csv', 'tsv', 'json', and-(multi-period reports only:) 'html'.  In 'txt' output in a-colour-supporting terminal, negative amounts are shown in red.--   The '--related'/'-r' flag shows the balance of the _other_ postings-in the transactions of the postings which would normally be shown.---File: hledger.info,  Node: Simple balance report,  Next: Balance report line format,  Prev: balance features,  Up: balance--24.6.2 Simple balance report-------------------------------With no arguments, 'balance' shows a list of all accounts and their-change of balance - ie, the sum of posting amounts, both inflows and-outflows - during the entire period of the journal.  ("Simple" here-means just one column of numbers, covering a single period.  You can-also have multi-period reports, described later.)--   For real-world accounts, these numbers will normally be their end-balance at the end of the journal period; more on this below.--   Accounts are sorted by declaration order if any, and then-alphabetically by account name.  For instance (using-examples/sample.journal):--$ hledger -f examples/sample.journal bal-                  $1  assets:bank:saving-                 $-2  assets:cash-                  $1  expenses:food-                  $1  expenses:supplies-                 $-1  income:gifts-                 $-1  income:salary-                  $1  liabilities:debts----------------------                   0  --   Accounts with a zero balance (and no non-zero subaccounts, in tree-mode - see below) are hidden by default.  Use '-E/--empty' to show them-(revealing 'assets:bank:checking' here):--$ hledger -f examples/sample.journal bal  -E-                   0  assets:bank:checking-                  $1  assets:bank:saving-                 $-2  assets:cash-                  $1  expenses:food-                  $1  expenses:supplies-                 $-1  income:gifts-                 $-1  income:salary-                  $1  liabilities:debts----------------------                   0  --   The total of the amounts displayed is shown as the last line, unless-'-N'/'--no-total' is used.---File: hledger.info,  Node: Balance report line format,  Next: Filtered balance report,  Prev: Simple balance report,  Up: balance--24.6.3 Balance report line format------------------------------------For single-period balance reports displayed in the terminal (only), you-can use '--format FMT' to customise the format and content of each line.-Eg:--$ hledger -f examples/sample.journal balance --format "%20(account) %12(total)"-              assets          $-1-         bank:saving           $1-                cash          $-2-            expenses           $2-                food           $1-            supplies           $1-              income          $-2-               gifts          $-1-              salary          $-1-   liabilities:debts           $1-----------------------------------                                0--   The FMT format string specifies the formatting applied to each-account/balance pair.  It may contain any suitable text, with data-fields interpolated like so:--   '%[MIN][.MAX](FIELDNAME)'--   * MIN pads with spaces to at least this width (optional)--   * MAX truncates at this width (optional)--   * FIELDNAME must be enclosed in parentheses, and can be one of:--        * 'depth_spacer' - a number of spaces equal to the account's-          depth, or if MIN is specified, MIN * depth spaces.-        * 'account' - the account's name-        * 'total' - the account's balance/posted total, right justified--   Also, FMT can begin with an optional prefix to control how-multi-commodity amounts are rendered:--   * '%_' - render on multiple lines, bottom-aligned (the default)-   * '%^' - render on multiple lines, top-aligned-   * '%,' - render on one line, comma-separated--   There are some quirks.  Eg in one-line mode, '%(depth_spacer)' has no-effect, instead '%(account)' has indentation built in.  Experimentation-may be needed to get pleasing results.--   Some example formats:--   * '%(total)' - the account's total-   * '%-20.20(account)' - the account's name, left justified, padded to-     20 characters and clipped at 20 characters-   * '%,%-50(account) %25(total)' - account name padded to 50-     characters, total padded to 20 characters, with multiple-     commodities rendered on one line-   * '%20(total) %2(depth_spacer)%-(account)' - the default format for-     the single-column balance report---File: hledger.info,  Node: Filtered balance report,  Next: List or tree mode,  Prev: Balance report line format,  Up: balance--24.6.4 Filtered balance report---------------------------------You can show fewer accounts, a different time period, totals from-cleared transactions only, etc.  by using query arguments or options to-limit the postings being matched.  Eg:--$ hledger -f examples/sample.journal bal --cleared assets date:200806-                 $-2  assets:cash----------------------                 $-2  ---File: hledger.info,  Node: List or tree mode,  Next: Depth limiting,  Prev: Filtered balance report,  Up: balance--24.6.5 List or tree mode---------------------------By default, or with '-l/--flat', accounts are shown as a flat list with-their full names visible, as in the examples above.--   With '-t/--tree', the account hierarchy is shown, with subaccounts'-"leaf" names indented below their parent:--$ hledger -f examples/sample.journal balance-                 $-1  assets-                  $1    bank:saving-                 $-2    cash-                  $2  expenses-                  $1    food-                  $1    supplies-                 $-2  income-                 $-1    gifts-                 $-1    salary-                  $1  liabilities:debts----------------------                   0--   Notes:--   * "Boring" accounts are combined with their subaccount for more-     compact output, unless '--no-elide' is used.  Boring accounts have-     no balance of their own and just one subaccount (eg 'assets:bank'-     and 'liabilities' above).--   * All balances shown are "inclusive", ie including the balances from-     all subaccounts.  Note this means some repetition in the output,-     which requires explanation when sharing reports with-     non-plaintextaccounting-users.  A tree mode report's final total is-     the sum of the top-level balances shown, not of all the balances-     shown.--   * Each group of sibling accounts (ie, under a common parent) is-     sorted separately.---File: hledger.info,  Node: Depth limiting,  Next: Dropping top-level accounts,  Prev: List or tree mode,  Up: balance--24.6.6 Depth limiting------------------------With a 'depth:NUM' query, or '--depth NUM' option, or just '-NUM' (eg:-'-3') balance reports will show accounts only to the specified depth,-hiding the deeper subaccounts.  This can be useful for getting an-overview without too much detail.--   Account balances at the depth limit always include the balances from-any deeper subaccounts (even in list mode).  Eg, limiting to depth 1:--$ hledger -f examples/sample.journal balance -1-                 $-1  assets-                  $2  expenses-                 $-2  income-                  $1  liabilities----------------------                   0  ---File: hledger.info,  Node: Dropping top-level accounts,  Next: Showing declared accounts,  Prev: Depth limiting,  Up: balance--24.6.7 Dropping top-level accounts-------------------------------------You can also hide one or more top-level account name parts, using-'--drop NUM'.  This can be useful for hiding repetitive top-level-account names:--$ hledger -f examples/sample.journal bal expenses --drop 1-                  $1  food-                  $1  supplies----------------------                  $2  ---File: hledger.info,  Node: Showing declared accounts,  Next: Sorting by amount,  Prev: Dropping top-level accounts,  Up: balance--24.6.8 Showing declared accounts-----------------------------------With '--declared', accounts which have been declared with an account-directive will be included in the balance report, even if they have no-transactions.  (Since they will have a zero balance, you will also need-'-E/--empty' to see them.)--   More precisely, _leaf_ declared accounts (with no subaccounts) will-be included, since those are usually the more useful in reports.--   The idea of this is to be able to see a useful "complete" balance-report, even when you don't have transactions in all of your declared-accounts yet.---File: hledger.info,  Node: Sorting by amount,  Next: Percentages,  Prev: Showing declared accounts,  Up: balance--24.6.9 Sorting by amount---------------------------With '-S/--sort-amount', accounts with the largest (most positive)-balances are shown first.  Eg: 'hledger bal expenses -MAS' shows your-biggest averaged monthly expenses first.  When more than one commodity-is present, they will be sorted by the alphabetically earliest commodity-first, and then by subsequent commodities (if an amount is missing a-commodity, it is treated as 0).--   Revenues and liability balances are typically negative, however, so-'-S' shows these in reverse order.  To work around this, you can add-'--invert' to flip the signs.  (Or, use one of the higher-level reports,-which flip the sign automatically.  Eg: 'hledger incomestatement -MAS').---File: hledger.info,  Node: Percentages,  Next: Multi-period balance report,  Prev: Sorting by amount,  Up: balance--24.6.10 Percentages----------------------With '-%/--percent', balance reports show each account's value expressed-as a percentage of the (column) total.--   Note it is not useful to calculate percentages if the amounts in a-column have mixed signs.  In this case, make a separate report for each-sign, eg:--$ hledger bal -% amt:`>0`-$ hledger bal -% amt:`<0`--   Similarly, if the amounts in a column have mixed commodities, convert-them to one commodity with '-B', '-V', '-X' or '--value', or make a-separate report for each commodity:--$ hledger bal -% cur:\\$-$ hledger bal -% cur:€---File: hledger.info,  Node: Multi-period balance report,  Next: Balance change end balance,  Prev: Percentages,  Up: balance--24.6.11 Multi-period balance report--------------------------------------With a report interval (set by the '-D/--daily', '-W/--weekly',-'-M/--monthly', '-Q/--quarterly', '-Y/--yearly', or '-p/--period' flag),-'balance' shows a tabular report, with columns representing successive-time periods (and a title):--$ hledger -f examples/sample.journal bal --quarterly income expenses -E-Balance changes in 2008:--                   ||  2008q1  2008q2  2008q3  2008q4 -===================++=================================- expenses:food     ||       0      $1       0       0 - expenses:supplies ||       0      $1       0       0 - income:gifts      ||       0     $-1       0       0 - income:salary     ||     $-1       0       0       0 --------------------++----------------------------------                   ||     $-1      $1       0       0 --   Notes:--   * The report's start/end dates will be expanded, if necessary, to-     fully encompass the displayed subperiods (so that the first and-     last subperiods have the same duration as the others).-   * Leading and trailing periods (columns) containing all zeroes are-     not shown, unless '-E/--empty' is used.-   * Accounts (rows) containing all zeroes are not shown, unless-     '-E/--empty' is used.-   * Amounts with many commodities are shown in abbreviated form, unless-     '--no-elide' is used.  _(experimental)_-   * Average and/or total columns can be added with the '-A/--average'-     and '-T/--row-total' flags.-   * The '--transpose' flag can be used to exchange rows and columns.-   * The '--pivot FIELD' option causes a different transaction field to-     be used as "account name".  See PIVOTING.--   Multi-period reports with many periods can be too wide for easy-viewing in the terminal.  Here are some ways to handle that:--   * Hide the totals row with '-N/--no-total'-   * Convert to a single currency with '-V'-   * Maximize the terminal window-   * Reduce the terminal's font size-   * View with a pager like less, eg: 'hledger bal -D --color=yes | less-     -RS'-   * Output as CSV and use a CSV viewer like visidata ('hledger bal -D-     -O csv | vd -f csv'), Emacs' csv-mode ('M-x csv-mode, C-c C-a'), or-     a spreadsheet ('hledger bal -D -o a.csv && open a.csv')-   * Output as HTML and view with a browser: 'hledger bal -D -o a.html-     && open a.html'---File: hledger.info,  Node: Balance change end balance,  Next: Balance report types,  Prev: Multi-period balance report,  Up: balance--24.6.12 Balance change, end balance--------------------------------------It's important to be clear on the meaning of the numbers shown in-balance reports.  Here is some terminology we use:--   A *_balance change_* is the net amount added to, or removed from, an-account during some period.--   An *_end balance_* is the amount accumulated in an account as of some-date (and some time, but hledger doesn't store that; assume end of day-in your timezone).  It is the sum of previous balance changes.--   We call it a *_historical end balance_* if it includes all balance-changes since the account was created.  For a real world account, this-means it will match the "historical record", eg the balances reported in-your bank statements or bank web UI. (If they are correct!)--   In general, balance changes are what you want to see when reviewing-revenues and expenses, and historical end balances are what you want to-see when reviewing or reconciling asset, liability and equity accounts.--   'balance' shows balance changes by default.  To see accurate-historical end balances:--  1. Initialise account starting balances with an "opening balances"-     transaction (a transfer from equity to the account), unless the-     journal covers the account's full lifetime.--  2. Include all of of the account's prior postings in the report, by-     not specifying a report start date, or by using the-     '-H/--historical' flag.  ('-H' causes report start date to be-     ignored when summing postings.)---File: hledger.info,  Node: Balance report types,  Next: Budget report,  Prev: Balance change end balance,  Up: balance--24.6.13 Balance report types-------------------------------The balance command is quite flexible; here is the full detail on how to-control what it reports.  If the following seems complicated, don't-worry - this is for advanced reporting, and it does take time and-experimentation to get familiar with all the report modes.--   There are three important option groups:--   'hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE]-...'--* Menu:--* Calculation type::-* Accumulation type::-* Valuation type::-* Combining balance report types::---File: hledger.info,  Node: Calculation type,  Next: Accumulation type,  Up: Balance report types--24.6.13.1 Calculation type-..........................--The basic calculation to perform for each table cell.  It is one of:--   * '--sum' : sum the posting amounts (*default*)-   * '--budget' : sum the amounts, but also show the budget goal amount-     (for each account/period)-   * '--valuechange' : show the change in period-end historical balance-     values (caused by deposits, withdrawals, and/or market price-     fluctuations)-   * '--gain' : show the unrealised capital gain/loss, (the current-     valued balance minus each amount's original cost)-   * '--count' : show the count of postings---File: hledger.info,  Node: Accumulation type,  Next: Valuation type,  Prev: Calculation type,  Up: Balance report types--24.6.13.2 Accumulation type-...........................--How amounts should accumulate across report periods.  Another way to say-it: which time period's postings should contribute to each cell's-calculation.  It is one of:--   * '--change' : calculate with postings from column start to column-     end, ie "just this column".  Typically used to see-     revenues/expenses.  (*default for balance, incomestatement*)--   * '--cumulative' : calculate with postings from report start to-     column end, ie "previous columns plus this column".  Typically used-     to show changes accumulated since the report's start date.  Not-     often used.--   * '--historical/-H' : calculate with postings from journal start to-     column end, ie "all postings from before report start date until-     this column's end".  Typically used to see historical end balances-     of assets/liabilities/equity.  (*default for balancesheet,-     balancesheetequity, cashflow*)---File: hledger.info,  Node: Valuation type,  Next: Combining balance report types,  Prev: Accumulation type,  Up: Balance report types--24.6.13.3 Valuation type-........................--Which kind of value or cost conversion should be applied, if any, before-displaying the report.  It is one of:--   * no valuation type : don't convert to cost or value (*default*)-   * '--value=cost[,COMM]' : convert amounts to cost (then optionally to-     some other commodity)-   * '--value=then[,COMM]' : convert amounts to market value on-     transaction dates-   * '--value=end[,COMM]' : convert amounts to market value on period-     end date(s)-     (*default with '--valuechange', '--gain'*)-   * '--value=now[,COMM]' : convert amounts to market value on today's-     date-   * '--value=YYYY-MM-DD[,COMM]' : convert amounts to market value on-     another date--   or one of the equivalent simpler flags:--   * '-B/--cost' : like -value=cost (though, note -cost and -value are-     independent options which can both be used at once)-   * '-V/--market' : like -value=end-   * '-X COMM/--exchange COMM' : like -value=end,COMM--   See Cost reporting and Value reporting for more about these.---File: hledger.info,  Node: Combining balance report types,  Prev: Valuation type,  Up: Balance report types--24.6.13.4 Combining balance report types-........................................--Most combinations of these options should produce reasonable reports,-but if you find any that seem wrong or misleading, let us know.  The-following restrictions are applied:--   * '--valuechange' implies '--value=end'-   * '--valuechange' makes '--change' the default when used with the-     'balancesheet'/'balancesheetequity' commands-   * '--cumulative' or '--historical' disables '--row-total/-T'--   For reference, here is what the combinations of accumulation and-valuation show:--Valuation:>no valuation    '--value= then'   '--value= end'   '--value=-Accumulation:v                                                YYYY-MM-DD-                                                              /now'-------------------------------------------------------------------------------'--change'change in        sum of            period-end       DATE-value-         period            posting-date      value of         of change in-                           market values     change in        period-                           in period         period-'--cumulative'change from  sum of            period-end       DATE-value-         report start to   posting-date      value of         of change-         period end        market values     change from      from report-                           from report       report start     start to-                           start to period   to period end    period end-                           end-'--historicalchange from   sum of            period-end       DATE-value-/-H'     journal start     posting-date      value of         of change-         to period end     market values     change from      from journal-         (historical end   from journal      journal start    start to-         balance)          start to period   to period end    period end-                           end---File: hledger.info,  Node: Budget report,  Next: Balance report layout,  Prev: Balance report types,  Up: balance--24.6.14 Budget report------------------------The '--budget' report type activates extra columns showing any budget-goals for each account and period.  The budget goals are defined by-periodic transactions.  This is useful for comparing planned and actual-income, expenses, time usage, etc.--   For example, you can take average monthly expenses in the common-expense categories to construct a minimal monthly budget:--;; Budget-~ monthly-  income  $2000-  expenses:food    $400-  expenses:bus     $50-  expenses:movies  $30-  assets:bank:checking--;; Two months worth of expenses-2017-11-01-  income  $1950-  expenses:food    $396-  expenses:bus     $49-  expenses:movies  $30-  expenses:supplies  $20-  assets:bank:checking--2017-12-01-  income  $2100-  expenses:food    $412-  expenses:bus     $53-  expenses:gifts   $100-  assets:bank:checking--   You can now see a monthly budget report:--$ hledger balance -M --budget-Budget performance in 2017/11/01-2017/12/31:--                      ||                      Nov                       Dec -======================++====================================================- assets               || $-2445 [  99% of $-2480]  $-2665 [ 107% of $-2480] - assets:bank          || $-2445 [  99% of $-2480]  $-2665 [ 107% of $-2480] - assets:bank:checking || $-2445 [  99% of $-2480]  $-2665 [ 107% of $-2480] - expenses             ||   $495 [ 103% of   $480]    $565 [ 118% of   $480] - expenses:bus         ||    $49 [  98% of    $50]     $53 [ 106% of    $50] - expenses:food        ||   $396 [  99% of   $400]    $412 [ 103% of   $400] - expenses:movies      ||    $30 [ 100% of    $30]       0 [   0% of    $30] - income               ||  $1950 [  98% of  $2000]   $2100 [ 105% of  $2000] -----------------------++-----------------------------------------------------                      ||      0 [              0]       0 [              0] --   This is different from a normal balance report in several ways.-Currently:--   * Accounts with budget goals during the report period, and their-     parents, are shown.-   * Their subaccounts are not shown (regardless of the depth setting).-   * Accounts without budget goals, if any, are aggregated and shown as-     "<unbudgeted>".-   * Amounts are always inclusive (subaccount-including), even in list-     mode.-   * After each actual amount, the corresponding goal amount and-     percentage of goal reached are also shown, in square brackets.--   This means that the numbers displayed will not always add up!  Eg-above, the 'expenses' actual amount includes the gifts and supplies-transactions, but the 'expenses:gifts' and 'expenses:supplies' accounts-are not shown, as they have no budget amounts declared.--   This can be confusing.  When you need to make things clearer, use the-'-E/--empty' flag, which will reveal all accounts including unbudgeted-ones, giving the full picture.  Eg:--$ hledger balance -M --budget --empty-Budget performance in 2017/11/01-2017/12/31:--                      ||                      Nov                       Dec -======================++====================================================- assets               || $-2445 [  99% of $-2480]  $-2665 [ 107% of $-2480] - assets:bank          || $-2445 [  99% of $-2480]  $-2665 [ 107% of $-2480] - assets:bank:checking || $-2445 [  99% of $-2480]  $-2665 [ 107% of $-2480] - expenses             ||   $495 [ 103% of   $480]    $565 [ 118% of   $480] - expenses:bus         ||    $49 [  98% of    $50]     $53 [ 106% of    $50] - expenses:food        ||   $396 [  99% of   $400]    $412 [ 103% of   $400] - expenses:gifts       ||      0                      $100                   - expenses:movies      ||    $30 [ 100% of    $30]       0 [   0% of    $30] - expenses:supplies    ||    $20                         0                   - income               ||  $1950 [  98% of  $2000]   $2100 [ 105% of  $2000] -----------------------++-----------------------------------------------------                      ||      0 [              0]       0 [              0] --   You can roll over unspent budgets to next period with '--cumulative':--$ hledger balance -M --budget --cumulative-Budget performance in 2017/11/01-2017/12/31:--                      ||                      Nov                       Dec -======================++====================================================- assets               || $-2445 [  99% of $-2480]  $-5110 [ 103% of $-4960] - assets:bank          || $-2445 [  99% of $-2480]  $-5110 [ 103% of $-4960] - assets:bank:checking || $-2445 [  99% of $-2480]  $-5110 [ 103% of $-4960] - expenses             ||   $495 [ 103% of   $480]   $1060 [ 110% of   $960] - expenses:bus         ||    $49 [  98% of    $50]    $102 [ 102% of   $100] - expenses:food        ||   $396 [  99% of   $400]    $808 [ 101% of   $800] - expenses:movies      ||    $30 [ 100% of    $30]     $30 [  50% of    $60] - income               ||  $1950 [  98% of  $2000]   $4050 [ 101% of  $4000] -----------------------++-----------------------------------------------------                      ||      0 [              0]       0 [              0] --   It's common to limit budgets/budget reports to just expenses--hledger bal -M --budget expenses--   or just revenues and expenses (eg, using account types):--hledger bal -M --budget type:rx--   It's also common to limit or convert them to a single currency-('cur:COMM' or '-X COMM [--infer-market-prices]').  If showing multiple-currencies, '--layout bare' or '--layout tall' can help.--   For more examples and notes, see Budgeting.--* Menu:--* Budget report start date::-* Budgets and subaccounts::-* Selecting budget goals::-* Budget vs forecast::---File: hledger.info,  Node: Budget report start date,  Next: Budgets and subaccounts,  Up: Budget report--24.6.14.1 Budget report start date-..................................--This might be a bug, but for now: when making budget reports, it's a-good idea to explicitly set the report's start date to the first day of-a reporting period, because a periodic rule like '~ monthly' generates-its transactions on the 1st of each month, and if your journal has no-regular transactions on the 1st, the default report start date could-exclude that budget goal, which can be a little surprising.  Eg here the-default report period is just the day of 2020-01-15:--~ monthly in 2020-  (expenses:food)  $500--2020-01-15-  expenses:food    $400-  assets:checking--$ hledger bal expenses --budget-Budget performance in 2020-01-15:--              || 2020-01-15 -==============++============- <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--24.6.14.2 Budgets and subaccounts-.................................--You can add budgets to any account in your account hierarchy.  If you-have budgets on both parent account and some of its children, then-budget(s) of the child account(s) would be added to the budget of their-parent, much like account balances behave.--   In the most simple case this means that once you add a budget to any-account, all its parents would have budget as well.--   To illustrate this, consider the following budget:--~ monthly from 2019/01-    expenses:personal             $1,000.00-    expenses:personal:electronics    $100.00-    liabilities--   With this, monthly budget for electronics is defined to be $100 and-budget for personal expenses is an additional $1000, which implicitly-means that budget for both 'expenses:personal' and 'expenses' is $1100.--   Transactions in 'expenses:personal:electronics' will be counted both-towards its $100 budget and $1100 of 'expenses:personal' , and-transactions in any other subaccount of 'expenses:personal' would be-counted towards only towards the budget of 'expenses:personal'.--   For example, let's consider these transactions:--~ monthly from 2019/01-    expenses:personal             $1,000.00-    expenses:personal:electronics    $100.00-    liabilities--2019/01/01 Google home hub-    expenses:personal:electronics          $90.00-    liabilities                           $-90.00--2019/01/02 Phone screen protector-    expenses:personal:electronics:upgrades          $10.00-    liabilities--2019/01/02 Weekly train ticket-    expenses:personal:train tickets       $153.00-    liabilities--2019/01/03 Flowers-    expenses:personal          $30.00-    liabilities--   As you can see, we have transactions in-'expenses:personal:electronics:upgrades' and 'expenses:personal:train-tickets', and since both of these accounts are without explicitly-defined budget, these transactions would be counted towards budgets of-'expenses:personal:electronics' and 'expenses:personal' accordingly:--$ hledger balance --budget -M-Budget performance in 2019/01:--                               ||                           Jan -===============================++===============================- expenses                      ||  $283.00 [  26% of  $1100.00] - expenses:personal             ||  $283.00 [  26% of  $1100.00] - expenses:personal:electronics ||  $100.00 [ 100% of   $100.00] - liabilities                   || $-283.00 [  26% of $-1100.00] --------------------------------++--------------------------------                               ||        0 [                 0] --   And with '--empty', we can get a better picture of budget allocation-and consumption:--$ hledger balance --budget -M --empty-Budget performance in 2019/01:--                                        ||                           Jan -========================================++===============================- expenses                               ||  $283.00 [  26% of  $1100.00] - expenses:personal                      ||  $283.00 [  26% of  $1100.00] - expenses:personal:electronics          ||  $100.00 [ 100% of   $100.00] - expenses:personal:electronics:upgrades ||   $10.00                      - expenses:personal:train tickets        ||  $153.00                      - liabilities                            || $-283.00 [  26% of $-1100.00] -----------------------------------------++--------------------------------                                        ||        0 [                 0] ---File: hledger.info,  Node: Selecting budget goals,  Next: Budget vs forecast,  Prev: Budgets and subaccounts,  Up: Budget report--24.6.14.3 Selecting budget goals-................................--The budget report evaluates periodic transaction rules to generate-special "goal transactions", which generate the goal amounts for each-account in each report subperiod.  When troubleshooting, you can use-'print --forecast' to show these as forecasted transactions:--$ hledger print --forecast=BUDGETREPORTPERIOD tag:generated--   By default, the budget report uses all available periodic transaction-rules to generate goals.  This includes rules with a different report-interval from your report.  Eg if you have daily, weekly and monthly-periodic rules, all of these will contribute to the goals in a monthly-budget report.--   You can select a subset of periodic rules by providing an argument to-the '--budget' flag.  '--budget=DESCPAT' will match all periodic rules-whose description contains DESCPAT, a case-insensitive substring (not a-regular expression or query).  This means you can give your periodic-rules descriptions (remember that two spaces are needed), and then-select from multiple budgets defined in your journal.---File: hledger.info,  Node: Budget vs forecast,  Prev: Selecting budget goals,  Up: Budget report--24.6.14.4 Budget vs forecast-............................--'hledger --forecast ...' and 'hledger balance --budget ...' are separate-features, though both of them use the periodic transaction rules defined-in the journal, and both of them generate temporary transactions for-reporting purposes ("forecast transactions" and "budget goal-transactions", respectively).  You can use both features at the same-time if you want.  Here are some differences between them, as of hledger-1.29:--   CLI:--   * -forecast is a general hledger option, usable with any command-   * -budget is a 'balance' command option, usable only with that-     command.--   Visibility of generated transactions:--   * forecast transactions are visible in any report, like ordinary-     transactions-   * budget goal transactions are invisible except for the goal amounts-     they produce in -budget reports.--   Periodic transaction rules:--   * -forecast uses all available periodic transaction rules-   * -budget uses all periodic rules ('--budget') or a selected subset-     ('--budget=DESCPAT')--   Period of generated transactions:--   * -forecast generates forecast transactions-        * from after the last regular transaction to the end of the-          report period ('--forecast')-        * or, during a specified period ('--forecast=PERIODEXPR')-        * possibly further restricted by a period specified in the-          periodic transaction rule-        * and always restricted within the bounds of the report period--   * -budget generates budget goal transactions-        * throughout the report period-        * possibly restricted by a period specified in the periodic-          transaction rule.---File: hledger.info,  Node: Balance report layout,  Next: Useful balance reports,  Prev: Budget report,  Up: balance--24.6.15 Balance report layout--------------------------------The '--layout' option affects how balance reports show multi-commodity-amounts and commodity symbols, which can improve readability.  It can-also normalise the data for easy consumption by other programs.  It has-four possible values:--   * '--layout=wide[,WIDTH]': commodities are shown on a single line,-     optionally elided to WIDTH-   * '--layout=tall': each commodity is shown on a separate line-   * '--layout=bare': commodity symbols are in their own column, amounts-     are bare numbers-   * '--layout=tidy': data is normalised to easily-consumed "tidy" form,-     with one row per data value--   Here are the '--layout' modes supported by each output format; note-only CSV output supports all of them:---      txt   csv   html   json   sql-----------------------------------------wide   Y     Y     Y-tall   Y     Y     Y-bare   Y     Y     Y-tidy         Y--   Examples:--   * Wide layout.  With many commodities, reports can be very wide:--     $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide-     Balance changes in 2012-01-01..2014-12-31:-     -                       ||                                          2012                                                     2013                                             2014                                                      Total -     ==================++====================================================================================================================================================================================================================-      Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT  70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT  -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT  70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT -     ------------------++---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------                       || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT  70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT  -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT  70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT --   * Limited wide layout.  A width limit reduces the width, but some-     commodities will be hidden:--     $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32-     Balance changes in 2012-01-01..2014-12-31:-     -                       ||                             2012                             2013                   2014                            Total -     ==================++===========================================================================================================================-      Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more..  70.00 GLD, 18.00 ITOT, 3 more..  -11.00 ITOT, 3 more..  70.00 GLD, 17.00 ITOT, 3 more.. -     ------------------++----------------------------------------------------------------------------------------------------------------------------                       || 10.00 ITOT, 337.18 USD, 2 more..  70.00 GLD, 18.00 ITOT, 3 more..  -11.00 ITOT, 3 more..  70.00 GLD, 17.00 ITOT, 3 more.. --   * Tall layout.  Each commodity gets a new line (may be different in-     each column), and account names are repeated:--     $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall-     Balance changes in 2012-01-01..2014-12-31:-     -                       ||       2012        2013         2014        Total -     ==================++==================================================-      Assets:US:ETrade || 10.00 ITOT   70.00 GLD  -11.00 ITOT    70.00 GLD -      Assets:US:ETrade || 337.18 USD  18.00 ITOT  4881.44 USD   17.00 ITOT -      Assets:US:ETrade ||  12.00 VEA  -98.12 USD    14.00 VEA  5120.50 USD -      Assets:US:ETrade || 106.00 VHT   10.00 VEA   170.00 VHT    36.00 VEA -      Assets:US:ETrade ||              18.00 VHT                294.00 VHT -     ------------------++---------------------------------------------------                       || 10.00 ITOT   70.00 GLD  -11.00 ITOT    70.00 GLD -                       || 337.18 USD  18.00 ITOT  4881.44 USD   17.00 ITOT -                       ||  12.00 VEA  -98.12 USD    14.00 VEA  5120.50 USD -                       || 106.00 VHT   10.00 VEA   170.00 VHT    36.00 VEA -                       ||              18.00 VHT                294.00 VHT --   * Bare layout.  Commodity symbols are kept in one column, each-     commodity gets its own report row, account names are repeated:--     $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare-     Balance changes in 2012-01-01..2014-12-31:-     -                       || Commodity    2012    2013     2014    Total -     ==================++=============================================-      Assets:US:ETrade || GLD             0   70.00        0    70.00 -      Assets:US:ETrade || ITOT        10.00   18.00   -11.00    17.00 -      Assets:US:ETrade || USD        337.18  -98.12  4881.44  5120.50 -      Assets:US:ETrade || VEA         12.00   10.00    14.00    36.00 -      Assets:US:ETrade || VHT        106.00   18.00   170.00   294.00 -     ------------------++----------------------------------------------                       || GLD             0   70.00        0    70.00 -                       || ITOT        10.00   18.00   -11.00    17.00 -                       || USD        337.18  -98.12  4881.44  5120.50 -                       || VEA         12.00   10.00    14.00    36.00 -                       || VHT        106.00   18.00   170.00   294.00 --   * Bare layout also affects CSV output, which is useful for producing-     data that is easier to consume, eg for making charts:--     $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare-     "account","commodity","balance"-     "Assets:US:ETrade","GLD","70.00"-     "Assets:US:ETrade","ITOT","17.00"-     "Assets:US:ETrade","USD","5120.50"-     "Assets:US:ETrade","VEA","36.00"-     "Assets:US:ETrade","VHT","294.00"-     "total","GLD","70.00"-     "total","ITOT","17.00"-     "total","USD","5120.50"-     "total","VEA","36.00"-     "total","VHT","294.00"--   * Note: bare layout will sometimes display an extra row for the-     no-symbol commodity, because of zero amounts (hledger treats zeroes-     as commodity-less, usually).  This can break 'hledger-bar'-     confusingly (workaround: add a 'cur:' query to exclude the-     no-symbol row).--   * Tidy layout produces normalised "tidy data", where every variable-     has its own column and each row represents a single data point.-     See-     https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html-     for more.  This is the easiest kind of data for other software to-     consume.  Here's how it looks:--     $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy-     "account","period","start_date","end_date","commodity","value"-     "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0"-     "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00"-     "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18"-     "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00"-     "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00"-     "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00"-     "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00"-     "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12"-     "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00"-     "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00"-     "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0"-     "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00"-     "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44"-     "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00"-     "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00"---File: hledger.info,  Node: Useful balance reports,  Prev: Balance report layout,  Up: balance--24.6.16 Useful balance reports---------------------------------Some frequently used 'balance' options/reports are:--   * 'bal -M revenues expenses'-     Show revenues/expenses in each month.  Also available as the-     'incomestatement' command.--   * 'bal -M -H assets liabilities'-     Show historical asset/liability balances at each month end.  Also-     available as the 'balancesheet' command.--   * 'bal -M -H assets liabilities equity'-     Show historical asset/liability/equity balances at each month end.-     Also available as the 'balancesheetequity' command.--   * 'bal -M assets not:receivable'-     Show changes to liquid assets in each month.  Also available as the-     'cashflow' command.--   Also:--   * 'bal -M expenses -2 -SA'-     Show monthly expenses summarised to depth 2 and sorted by average-     amount.--   * 'bal -M --budget expenses'-     Show monthly expenses and budget goals.--   * 'bal -M --valuechange investments'-     Show monthly change in market value of investment assets.--   * 'bal investments --valuechange -D date:lastweek amt:'>1000' -STA-     [--invert]'-     Show top gainers [or losers] last week---File: hledger.info,  Node: balancesheet,  Next: balancesheetequity,  Prev: balance,  Up: PART 4 COMMANDS--24.7 balancesheet-=================--(bs)--   This command displays a balance sheet, showing historical ending-balances of asset and liability accounts.  (To see equity as well, use-the balancesheetequity command.)  Amounts are shown with normal positive-sign, as in conventional financial statements.--   This report shows accounts declared with the 'Asset', 'Cash' or-'Liability' type (see account types).  Or if no such accounts are-declared, it shows top-level accounts named 'asset' or 'liability' (case-insensitive, plurals allowed) and their subaccounts.--   Example:--$ hledger balancesheet-Balance Sheet--Assets:-                 $-1  assets-                  $1    bank:saving-                 $-2    cash----------------------                 $-1--Liabilities:-                  $1  liabilities:debts----------------------                  $1--Total:----------------------                   0--   This command is a higher-level variant of the 'balance' command, and-supports many of that command's features, such as multi-period reports.-It is similar to 'hledger balance -H assets liabilities', but with-smarter account detection, and liabilities displayed with their sign-flipped.--   This command also supports the output destination and output format-options The output formats supported are 'txt', 'csv', 'tsv', 'html',-and (experimental) 'json'.---File: hledger.info,  Node: balancesheetequity,  Next: cashflow,  Prev: balancesheet,  Up: PART 4 COMMANDS--24.8 balancesheetequity-=======================--(bse)--   This command displays a balance sheet, showing historical ending-balances of asset, liability and equity accounts.  Amounts are shown-with normal positive sign, as in conventional financial statements.--   This report shows accounts declared with the 'Asset', 'Cash',-'Liability' or 'Equity' type (see account types).  Or if no such-accounts are declared, it shows top-level accounts named 'asset',-'liability' or 'equity' (case insensitive, plurals allowed) and their-subaccounts.--   Example:--$ hledger balancesheetequity-Balance Sheet With Equity--Assets:-                 $-2  assets-                  $1    bank:saving-                 $-3    cash----------------------                 $-2--Liabilities:-                  $1  liabilities:debts----------------------                  $1--Equity:-          $1  equity:owner----------------------          $1--Total:----------------------                   0--   This command is a higher-level variant of the 'balance' command, and-supports many of that command's features, such as multi-period reports.-It is similar to 'hledger balance -H assets liabilities equity', but-with smarter account detection, and liabilities/equity displayed with-their sign flipped.--   This command also supports the output destination and output format-options The output formats supported are 'txt', 'csv', 'tsv', 'html',-and (experimental) 'json'.---File: hledger.info,  Node: cashflow,  Next: check,  Prev: balancesheetequity,  Up: PART 4 COMMANDS--24.9 cashflow-=============--(cf)--   This command displays a cashflow statement, showing the inflows and-outflows affecting "cash" (ie, liquid, easily convertible) assets.-Amounts are shown with normal positive sign, as in conventional-financial statements.--   This report shows accounts declared with the 'Cash' type (see account-types).  Or if no such accounts are declared, it shows accounts--   * under a top-level account named 'asset' (case insensitive, plural-     allowed)-   * whose name contains some variation of 'cash', 'bank', 'checking' or-     'saving'.--   More precisely: all accounts matching this case insensitive regular-expression:--   '^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$)'--   and their subaccounts.--   An example cashflow report:--$ hledger cashflow-Cashflow Statement--Cash flows:-                 $-1  assets-                  $1    bank:saving-                 $-2    cash----------------------                 $-1--Total:----------------------                 $-1--   This command is a higher-level variant of the 'balance' command, and-supports many of that command's features, such as multi-period reports.-It is similar to 'hledger balance assets not:fixed not:investment-not:receivable', but with smarter account detection.--   This command also supports the output destination and output format-options The output formats supported are 'txt', 'csv', 'tsv', 'html',-and (experimental) 'json'.---File: hledger.info,  Node: check,  Next: close,  Prev: cashflow,  Up: PART 4 COMMANDS--24.10 check-===========--Check for various kinds of errors in your data.--   hledger provides a number of built-in error checks to help prevent-problems in your data.  Some of these are run automatically; or, you can-use this 'check' command to run them on demand, with no output and a-zero exit code if all is well.  Specify their names (or a prefix) as-argument(s).--   Some examples:--hledger check      # basic checks-hledger check -s   # basic + strict checks-hledger check ordereddates payees  # basic + two other checks--   If you are an Emacs user, you can also configure flycheck-hledger to-run these checks, providing instant feedback as you edit the journal.--   Here are the checks currently available:--* Menu:--* Default checks::-* Strict checks::-* Other checks::-* Custom checks::-* More about specific checks::---File: hledger.info,  Node: Default checks,  Next: Strict checks,  Up: check--24.10.1 Default checks-------------------------These checks are run automatically by (almost) all hledger commands:--   * *parseable* - data files are in a supported format, with no syntax-     errors and no invalid include directives.--   * *autobalanced* - all transactions are balanced, after converting to-     cost.  Missing amounts and missing costs are inferred automatically-     where possible.--   * *assertions* - all balance assertions in the journal are passing.-     (This check can be disabled with '-I'/'--ignore-assertions'.)---File: hledger.info,  Node: Strict checks,  Next: Other checks,  Prev: Default checks,  Up: check--24.10.2 Strict checks------------------------These additional checks are run when the '-s'/'--strict' (strict mode)-flag is used.  Or, they can be run by giving their names as arguments to-'check':--   * *balanced* - all transactions are balanced after converting to-     cost, without inferring missing costs.  If conversion costs are-     required, they must be explicit.--   * *accounts* - all account names used by transactions have been-     declared--   * *commodities* - all commodity symbols used have been declared---File: hledger.info,  Node: Other checks,  Next: Custom checks,  Prev: Strict checks,  Up: check--24.10.3 Other checks-----------------------These checks can be run only by giving their names as arguments to-'check'.  They are more specialised and not desirable for everyone:--   * *ordereddates* - transactions are ordered by date within each file--   * *payees* - all payees used by transactions have been declared--   * *recentassertions* - all accounts with balance assertions have a-     balance assertion within 7 days of their latest posting--   * *tags* - all tags used by transactions have been declared--   * *uniqueleafnames* - all account leaf names are unique---File: hledger.info,  Node: Custom checks,  Next: More about specific checks,  Prev: Other checks,  Up: check--24.10.4 Custom checks------------------------A few more checks are are available as separate add-on commands, in-https://github.com/simonmichael/hledger/tree/master/bin:--   * *hledger-check-tagfiles* - all tag values containing / (a forward-     slash) exist as file paths--   * *hledger-check-fancyassertions* - more complex balance assertions-     are passing--   You could make similar scripts to perform your own custom checks.-See: Cookbook -> Scripting.---File: hledger.info,  Node: More about specific checks,  Prev: Custom checks,  Up: check--24.10.5 More about specific checks-------------------------------------'hledger check recentassertions' will complain if any balance-asserted-account has postings more than 7 days after its latest balance-assertion.  This aims to prevent the situation where you are regularly-updating your journal, but forgetting to check your balances against the-real world, then one day must dig back through months of data to find an-error.  It assumes that adding a balance assertion requires/reminds you-to check the real-world balance.  (That may not be true if you-auto-generate balance assertions from bank data; in that case, I-recommend to import transactions uncleared, and when you manually review-and clear them, also check the latest assertion against the real-world-balance.)---File: hledger.info,  Node: close,  Next: codes,  Prev: check,  Up: PART 4 COMMANDS--24.11 close-===========--(equity)--   Generate transactions which transfer account balances to and/or from-another account (typically equity).  This can be useful for migrating-balances to a new journal file, or for merging earnings into equity at-end of accounting period.--   By default, it prints a transaction that zeroes out ALE accounts-(asset, liability, equity accounts; this requires account types to be-configured); or if ACCTQUERY is provided, the accounts matched by that.--   _(experimental)_--   This command has four main modes, corresponding to the most common-use cases:--  1. With '--close' (default), it prints a "closing balances"-     transaction that zeroes out ALE (asset, liability, equity) accounts-     by default (this requires account types to be inferred or-     declared); or, the accounts matched by the provided ACCTQUERY-     arguments.--  2. With '--open', it prints an opposite "opening balances" transaction-     that restores those balances from zero.  This is similar to-     Ledger's equity command.--  3. With '--migrate', it prints both the closing and opening-     transactions.  This is the preferred way to migrate balances to a-     new file: run 'hledger close --migrate', add the closing-     transaction at the end of the old file, and add the opening-     transaction at the start of the new file.  The matching-     closing/opening transactions cancel each other out, preserving-     correct balances during multi-file reporting.--  4. With '--retain', it prints a "retain earnings" transaction that-     transfers RX (revenue and expense) balances to 'equity:retained-     earnings'.  Businesses traditionally do this at the end of each-     accounting period; it is less necessary with computer-based-     accounting, but it could still be useful if you want to see the-     accounting equation (A=L+E) satisfied.--   In all modes, the defaults can be overridden:--   * the transaction descriptions can be changed with-     '--close-desc=DESC' and '--open-desc=DESC'-   * the account to transfer to/from can be changed with-     '--close-acct=ACCT' and '--open-acct=ACCT'-   * the accounts to be closed/opened can be changed with 'ACCTQUERY'-     (account query arguments).-   * the closing/opening dates can be changed with '-e DATE' (a report-     end date)--   By default just one destination/source posting will be used, with its-amount left implicit.  With '--x/--explicit', the amount will be shown-explicitly, and if it involves multiple commodities, a separate posting-will be generated for each of them (similar to 'print -x').--   With '--show-costs', any amount costs are shown, with separate-postings for each cost.  This is currently the best way to view-investment lots.  If you have many currency conversion or investment-transactions, it can generate very large journal entries.--   With '--interleaved', each individual transfer is shown with source-and destination postings next to each other.  This could be useful for-troubleshooting.--   The default closing date is yesterday, or the journal's end date,-whichever is later.  You can change this by specifying a report end date-with '-e'.  The last day of the report period will be the closing date,-eg '-e 2024' means "close on 2023-12-31".  The opening date is always-the day after the closing date.--* Menu:--* close and balance assertions::-* Example retain earnings::-* Example migrate balances to a new file::-* Example excluding closing/opening transactions::---File: hledger.info,  Node: close and balance assertions,  Next: Example retain earnings,  Up: close--24.11.1 close and balance assertions---------------------------------------Balance assertions will be generated, verifying that the accounts have-been reset to zero (and then restored to their previous balances, if-there is an opening transaction).--   These provide useful error checking, but you can ignore them-temporarily with '-I', or remove them if you prefer.--   You probably should avoid filtering transactions by status or-realness ('-C', '-R', 'status:'), or generating postings ('--auto'),-with this command, since the balance assertions would depend on these.--   Note custom posting dates spanning the file boundary will disrupt the-balance assertions:--2023-12-30 a purchase made in december, cleared in january-    expenses:food          5-    assets:bank:checking  -5  ; date: 2023-01-02--   To solve that you can transfer the money to and from a temporary-account, in effect splitting the multi-day transaction into two-single-day transactions:--; in 2022.journal:-2022-12-30 a purchase made in december, cleared in january-    expenses:food          5-    equity:pending        -5--; in 2023.journal:-2023-01-02 last year's transaction cleared-    equity:pending         5 = 0-    assets:bank:checking  -5---File: hledger.info,  Node: Example retain earnings,  Next: Example migrate balances to a new file,  Prev: close and balance assertions,  Up: close--24.11.2 Example: retain earnings-----------------------------------Record 2022's revenues/expenses as retained earnings on 2022-12-31,-appending the generated transaction to the journal:--$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal--   Note 2022's income statement will now show only zeroes, because-revenues and expenses have been moved entirely to equity.  To see them-again, you could exclude the retain transaction:--$ hledger -f 2022.journal is not:desc:'retain earnings'---File: hledger.info,  Node: Example migrate balances to a new file,  Next: Example excluding closing/opening transactions,  Prev: Example retain earnings,  Up: close--24.11.3 Example: migrate balances to a new file--------------------------------------------------Close assets/liabilities/equity on 2022-12-31 and re-open them on-2023-01-01:--$ hledger close --migrate -f 2022.journal -p 2022-# copy/paste the closing transaction to the end of 2022.journal-# copy/paste the opening transaction to the start of 2023.journal--   Now 2022's balance sheet will show only zeroes, indicating a balanced-accounting equation.  (Unless you are using @/@@ notation - in that-case, try adding -infer-equity.)  To see the end-of-year balances again,-you could exclude the closing transaction:--$ hledger -f 2022.journal bs not:desc:'closing balances'---File: hledger.info,  Node: Example excluding closing/opening transactions,  Prev: Example migrate balances to a new file,  Up: close--24.11.4 Example: excluding closing/opening transactions----------------------------------------------------------When combining many files for multi-year reports, the closing/opening-transactions cause some noise in transaction-oriented reports like-'print' and 'register'.  You can exclude them as shown above, but-'not:desc:...' is not ideal as it depends on consistent descriptions;-also you will want to avoid excluding the very first opening-transaction, which could be awkward.  Here is one alternative, using-tags:--   Add 'clopen:' tags to all opening/closing balances transactions-except the first, like this:--; 2021.journal-2021-06-01 first opening balances-...-2021-12-31 closing balances  ; clopen:2022-...--; 2022.journal-2022-01-01 opening balances  ; clopen:2022-...-2022-12-31 closing balances  ; clopen:2023-...--; 2023.journal-2023-01-01 opening balances  ; clopen:2023-...--   Now, assuming a combined journal like:--; all.journal-include 2021.journal-include 2022.journal-include 2023.journal--   The 'clopen:' tag can exclude all but the first opening transaction.-To show a clean multi-year checking register:--$ hledger -f all.journal areg checking not:tag:clopen--   And the year values allow more precision.  To show 2022's year-end-balance sheet:--$ hledger -f all.journal bs -e2023 not:tag:clopen=2023---File: hledger.info,  Node: codes,  Next: commodities,  Prev: close,  Up: PART 4 COMMANDS--24.12 codes-===========--List the codes seen in transactions, in the order parsed.--   This command prints the value of each transaction's code field, in-the order transactions were parsed.  The transaction code is an optional-value written in parentheses between the date and description, often-used to store a cheque number, order number or similar.--   Transactions aren't required to have a code, and missing or empty-codes will not be shown by default.  With the '-E'/'--empty' flag, they-will be printed as blank lines.--   You can add a query to select a subset of transactions.--   Examples:--2022/1/1 (123) Supermarket   - Food       $5.00- Checking    --2022/1/2 (124) Post Office- Postage    $8.32- Checking--2022/1/3 Supermarket- Food      $11.23- Checking --2022/1/4 (126) Post Office- Postage    $3.21- Checking--$ hledger codes-123-124-126--$ hledger codes -E-123-124--126---File: hledger.info,  Node: commodities,  Next: demo,  Prev: codes,  Up: PART 4 COMMANDS--24.13 commodities-=================--List all commodity/currency symbols used or declared in the journal.---File: hledger.info,  Node: demo,  Next: descriptions,  Prev: commodities,  Up: PART 4 COMMANDS--24.14 demo-==========--Play demos of hledger usage in the terminal, if asciinema is installed.--   Run this command with no argument to list the demos.  To play a demo,-write its number or a prefix or substring of its title.  Tips:--   Make your terminal window large enough to see the demo clearly.--   Use the -s/-speed SPEED option to set your preferred playback speed,-eg '-s4' to play at 4x original speed or '-s.5' to play at half speed.-The default speed is 2x.--   Other asciinema options can be added following a double dash, eg '----i.1' to limit pauses or '-- -h' to list asciinema's other options.--   During playback, several keys are available: SPACE to pause/unpause,-.  to step forward (while paused), CTRL-c quit.--   Examples:--$ hledger demo               # list available demos-$ hledger demo 1             # play the first demo at default speed (2x)-$ hledger demo install -s4   # play the "install" demo at 4x speed---File: hledger.info,  Node: descriptions,  Next: diff,  Prev: demo,  Up: PART 4 COMMANDS--24.15 descriptions-==================--List the unique descriptions that appear in transactions.--   This command lists the unique descriptions that appear in-transactions, in alphabetic order.  You can add a query to select a-subset of transactions.--   Example:--$ hledger descriptions-Store Name-Gas Station | Petrol-Person A---File: hledger.info,  Node: diff,  Next: files,  Prev: descriptions,  Up: PART 4 COMMANDS--24.16 diff-==========--Compares a particular account's transactions in two input files.  It-shows any transactions to this account which are in one file but not in-the other.--   More precisely, for each posting affecting this account in either-file, it looks for a corresponding posting in the other file which posts-the same amount to the same account (ignoring date, description, etc.)-Since postings not transactions are compared, this also works when-multiple bank transactions have been combined into a single journal-entry.--   This is useful eg if you have downloaded an account's transactions-from your bank (eg as CSV data).  When hledger and your bank disagree-about the account balance, you can compare the bank data with your-journal to find out the cause.--   Examples:--$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro -These transactions are in the first file only:--2014/01/01 Opening Balances-    assets:bank:giro              EUR ...-    ...-    equity:opening balances       EUR -...--These transactions are in the second file only:---File: hledger.info,  Node: files,  Next: help,  Prev: diff,  Up: PART 4 COMMANDS--24.17 files-===========--List all files included in the journal.  With a REGEX argument, only-file names matching the regular expression (case sensitive) are shown.---File: hledger.info,  Node: help,  Next: import,  Prev: files,  Up: PART 4 COMMANDS--24.18 help-==========--Show the hledger user manual in the terminal, with 'info', 'man', or a-pager.  With a TOPIC argument, open it at that topic if possible.  TOPIC-can be any heading in the manual, or a heading prefix, case insensitive.-Eg: 'commands', 'print', 'forecast', 'journal', 'amount', '"auto-postings"'.--   This command shows the hledger manual built in to your hledger-version.  It can be useful when offline, or when you prefer the terminal-to a web browser, or when the appropriate hledger manual or viewing-tools are not installed on your system.--   By default it chooses the best viewer found in $PATH, trying (in this-order): 'info', 'man', '$PAGER', 'less', 'more'.  You can force the use-of info, man, or a pager with the '-i', '-m', or '-p' flags, If no-viewer can be found, or the command is run non-interactively, it just-prints the manual to stdout.--   If using 'info', note that version 6 or greater is needed for TOPIC-lookup.  If you are on mac you will likely have info 4.8, and should-consider installing a newer version, eg with 'brew install texinfo'-(#1770).--   Examples--$ hledger help --help      # show how the help command works-$ hledger help             # show the hledger manual with info, man or $PAGER-$ hledger help journal     # show the journal topic in the hledger manual-$ hledger help -m journal  # show it with man, even if info is installed---File: hledger.info,  Node: import,  Next: incomestatement,  Prev: help,  Up: PART 4 COMMANDS--24.19 import-============--Read new transactions added to each FILE provided as arguments since-last run, and add them to the journal.  Or with -dry-run, just print the-transactions that would be added.  Or with -catchup, just mark all of-the FILEs' current transactions as imported, without importing them.--   This command may append new transactions to the main journal file-(which should be in journal format).  Existing transactions are not-changed.  This is one of the few hledger commands that writes to the-journal file (see also 'add').--   Unlike other hledger commands, with 'import' the journal file is an-output file, and will be modified, though only by appending (existing-data will not be changed).  The input files are specified as arguments,-so to import one or more CSV files to your main journal, you will run-'hledger import bank.csv' or perhaps 'hledger import *.csv'.--   Note you can import from any file format, though CSV files are the-most common import source, and these docs focus on that case.--* Menu:--* Deduplication::-* Import testing::-* Importing balance assignments::-* Commodity display styles::---File: hledger.info,  Node: Deduplication,  Next: Import testing,  Up: import--24.19.1 Deduplication------------------------'import' does _time-based deduplication_, to detect only the new-transactions since the last successful import.  (This does not mean-"ignore transactions that look the same", but rather "ignore-transactions that have been seen before".)  This is intended for when-you are periodically importing downloaded data, which may overlap with-previous downloads.  Eg if every week (or every day) you download a-bank's last three months of CSV data, you can safely run 'hledger import-thebank.csv' each time and only new transactions will be imported.--   Since the items being read (CSV records, eg) often do not come with-unique identifiers, hledger detects new transactions by date, assuming-that:--  1. new items always have the newest dates-  2. item dates do not change across reads-  3. and items with the same date remain in the same relative order-     across reads.--   These are often true of CSV files representing transactions, or true-enough so that it works pretty well in practice.  1 is important, but-violations of 2 and 3 amongst the old transactions won't matter (and if-you import often, the new transactions will be few, so less likely to be-the ones affected).--   hledger remembers the latest date processed in each input file by-saving a hidden ".latest.FILE" file in FILE's directory (after a-succesful import).--   Eg when reading 'finance/bank.csv', it will look for and update the-'finance/.latest.bank.csv' state file.  The format is simple: one or-more lines containing the same ISO-format date (YYYY-MM-DD), meaning "I-have processed transactions up to this date, and this many of them on-that date."  Normally you won't see or manipulate these state files-yourself.  But if needed, you can delete them to reset the state (making-all transactions "new"), or you can construct them to "catch up" to a-certain date.--   Note deduplication (and updating of state files) can also be done by-'print --new', but this is less often used.--   Related: CSV > Working with CSV > Deduplicating, importing.---File: hledger.info,  Node: Import testing,  Next: Importing balance assignments,  Prev: Deduplication,  Up: import--24.19.2 Import testing-------------------------With '--dry-run', the transactions that will be imported are printed to-the terminal, without updating your journal or state files.  The output-is valid journal format, like the print command, so you can re-parse it.-Eg, to see any importable transactions which CSV rules have not-categorised:--$ hledger import --dry bank.csv | hledger -f- -I print unknown--   or (live updating):--$ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown'--   Note: when importing from multiple files at once, it's currently-possible for some .latest files to be updated successfully, while the-actual import fails because of a problem in one of the files, leaving-them out of sync (and causing some transactions to be missed).  To-prevent this, do a -dry-run first and fix any problems before the real-import.---File: hledger.info,  Node: Importing balance assignments,  Next: Commodity display styles,  Prev: Import testing,  Up: import--24.19.3 Importing balance assignments----------------------------------------Entries added by import will have their posting amounts made explicit-(like 'hledger print -x').  This means that any balance assignments in-imported files must be evaluated; but, imported files don't get to see-the main file's account balances.  As a result, importing entries with-balance assignments (eg from an institution that provides only balances-and not posting amounts) will probably generate incorrect posting-amounts.  To avoid this problem, use print instead of import:--$ hledger print IMPORTFILE [--new] >> $LEDGER_FILE--   (If you think import should leave amounts implicit like print does,-please test it and send a pull request.)---File: hledger.info,  Node: Commodity display styles,  Prev: Importing balance assignments,  Up: import--24.19.4 Commodity display styles-----------------------------------Imported amounts will be formatted according to the canonical commodity-styles (declared or inferred) in the main journal file.---File: hledger.info,  Node: incomestatement,  Next: notes,  Prev: import,  Up: PART 4 COMMANDS--24.20 incomestatement-=====================--(is)--   This command displays an income statement, showing revenues and-expenses during one or more periods.  Amounts are shown with normal-positive sign, as in conventional financial statements.--   This report shows accounts declared with the 'Revenue' or 'Expense'-type (see account types).  Or if no such accounts are declared, it shows-top-level accounts named 'revenue' or 'income' or 'expense' (case-insensitive, plurals allowed) and their subaccounts.--   Example:--$ hledger incomestatement-Income Statement--Revenues:-                 $-2  income-                 $-1    gifts-                 $-1    salary----------------------                 $-2--Expenses:-                  $2  expenses-                  $1    food-                  $1    supplies----------------------                  $2--Total:----------------------                   0--   This command is a higher-level variant of the 'balance' command, and-supports many of that command's features, such as multi-period reports.-It is similar to 'hledger balance '(revenues|income)' expenses', but-with smarter account detection, and revenues/income displayed with their-sign flipped.--   This command also supports the output destination and output format-options The output formats supported are 'txt', 'csv', 'tsv', 'html',-and (experimental) 'json'.---File: hledger.info,  Node: notes,  Next: payees,  Prev: incomestatement,  Up: PART 4 COMMANDS--24.21 notes-===========--List the unique notes that appear in transactions.--   This command lists the unique notes that appear in transactions, in-alphabetic order.  You can add a query to select a subset of-transactions.  The note is the part of the transaction description after-a | character (or if there is no |, the whole description).--   Example:--$ hledger notes-Petrol-Snacks---File: hledger.info,  Node: payees,  Next: prices,  Prev: notes,  Up: PART 4 COMMANDS--24.22 payees-============--List the unique payee/payer names that appear in transactions.--   This command lists unique payee/payer names which have been declared-with payee directives (-declared), used in transaction descriptions-(-used), or both (the default).--   The payee/payer is the part of the transaction description before a |-character (or if there is no |, the whole description).--   You can add query arguments to select a subset of transactions.  This-implies -used.--   Example:--$ hledger payees-Store Name-Gas Station-Person A---File: hledger.info,  Node: prices,  Next: print,  Prev: payees,  Up: PART 4 COMMANDS--24.23 prices-============--Print the market prices declared with P directives.  With--infer-market-prices, also show any additional prices inferred from-costs.  With -show-reverse, also show additional prices inferred by-reversing known prices.--   Price amounts are always displayed with their full precision, except-for reverse prices which are limited to 8 decimal digits.--   Prices can be filtered by a date:, cur: or amt: query.--   Generally if you run this command with -infer-market-prices--show-reverse, it will show the same prices used internally to calculate-value reports.  But if in doubt, you can inspect those directly by-running the value report with -debug=2.---File: hledger.info,  Node: print,  Next: register,  Prev: prices,  Up: PART 4 COMMANDS--24.24 print-===========--Show transaction journal entries, sorted by date.--   The print command displays full journal entries (transactions) from-the journal file, sorted by date (or with '--date2', by secondary date).--   Directives and inter-transaction comments are not shown, currently.-This means the print command is somewhat lossy, and if you are using it-to reformat/regenerate your journal you should take care to also copy-over the directives and inter-transaction comments.--   Eg:--$ hledger print -f examples/sample.journal date:200806-2008/06/01 gift-    assets:bank:checking            $1-    income:gifts                   $-1--2008/06/02 save-    assets:bank:saving              $1-    assets:bank:checking           $-1--2008/06/03 * eat & shop-    expenses:food                $1-    expenses:supplies            $1-    assets:cash                 $-2--* Menu:--* print explicitness::-* print amount style::-* print parseability::-* print other features::-* print output format::---File: hledger.info,  Node: print explicitness,  Next: print amount style,  Up: print--24.24.1 print explicitness-----------------------------Normally, whether posting amounts are implicit or explicit is preserved.-For example, when an amount is omitted in the journal, it will not-appear in the output.  Similarly, if a conversion cost is implied but-not written, it will not appear in the output.--   You can use the '-x'/'--explicit' flag to force explicit display of-all amounts and costs.  This can be useful for troubleshooting or for-making your journal more readable and robust against data entry errors.-'-x' is also implied by using any of '-B','-V','-X','--value'.--   The '-x'/'--explicit' flag will cause any postings with a-multi-commodity amount (which can arise when a multi-commodity-transaction has an implicit amount) to be split into multiple-single-commodity postings, keeping the output parseable.---File: hledger.info,  Node: print amount style,  Next: print parseability,  Prev: print explicitness,  Up: print--24.24.2 print amount style-----------------------------Amounts are shown right-aligned within each transaction (but not aligned-across all transactions; you can do that with ledger-mode in Emacs).--   Amounts will be (mostly) normalised to their commodity display style:-their symbol placement, decimal mark, and digit group marks will be made-consistent.  By default, decimal digits are shown as they are written in-the journal.--   With the '--round' option, 'print' will try increasingly hard to-display decimal digits according to the commodity display styles:--   * '--round=none' show amounts with original precisions (default)-   * '--round=soft' add/remove decimal zeros in amounts (except costs)-   * '--round=hard' round amounts (except costs), possibly hiding-     significant digits-   * '--round=all' round all amounts and costs--   'soft' is good for non-lossy cleanup, formatting amounts more-consistently where it's safe to do so.--   'hard' and 'all' can cause 'print' to show invalid unbalanced journal-entries; they may be useful eg for stronger cleanup, with manual fixups-when needed.---File: hledger.info,  Node: print parseability,  Next: print other features,  Prev: print amount style,  Up: print--24.24.3 print parseability-----------------------------print's output is usually a valid hledger journal, and you can process-it again with a second hledger command.  This can be useful for certain-kinds of search (though the same can be achieved with 'expr:' queries-now):--# Show running total of food expenses paid from cash.-# -f- reads from stdin. -I/--ignore-assertions is sometimes needed.-$ hledger print assets:cash | hledger -f- -I reg expenses:food--   There are some situations where print's output can become-unparseable:--   * Value reporting affects posting amounts but not balance assertion-     or balance assignment amounts, potentially causing those to fail.-   * Auto postings can generate postings with too many missing amounts.-   * Account aliases can generate bad account names.---File: hledger.info,  Node: print other features,  Next: print output format,  Prev: print parseability,  Up: print--24.24.4 print, other features--------------------------------With '-B'/'--cost', amounts with costs are shown converted to cost.--   With '--new', print shows only transactions it has not seen on a-previous run.  This uses the same deduplication system as the 'import'-command.  (See import's docs for details.)--   With '-m DESC'/'--match=DESC', print shows one recent transaction-whose description is most similar to DESC. DESC should contain at least-two characters.  If there is no similar-enough match, no transaction-will be shown and the program exit code will be non-zero.---File: hledger.info,  Node: print output format,  Prev: print other features,  Up: print--24.24.5 print output format------------------------------This command also supports the output destination and output format-options The output formats supported are 'txt', 'beancount', 'csv',-'tsv', 'json' and 'sql'.--   _Experimental:_ The 'beancount' format tries to produce-Beancount-compatible output, as follows:--   * Transaction and postings with unmarked status are converted to-     cleared ('*') status.-   * Transactions' payee and note are backslash-escaped and-     double-quote-escaped and wrapped in double quotes.-   * Transaction tags are copied to Beancount #tag format.-   * Commodity symbols are converted to upper case, and a small number-     of currency symbols like '$' are converted to the corresponding-     currency names.-   * Account name parts are capitalised and unsupported characters are-     replaced with '-'.  If an account name part does not begin with a-     letter, or if the first part is not Assets, Liabilities, Equity,-     Income, or Expenses, an error is raised.  (Use '--alias' options to-     bring your accounts into compliance.)-   * An 'open' directive is generated for each account used, on the-     earliest transaction date.--   Some limitations:--   * Balance assertions are removed.-   * Balance assignments become missing amounts.-   * Virtual and balanced virtual postings become regular postings.-   * Directives are not converted.--   Here's an example of print's CSV output:--$ hledger print -Ocsv-"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment"-"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","",""-"1","2008/01/01","","","","income","","income:salary","-1","$","1","","",""-"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","",""-"2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","",""-"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","",""-"3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","",""-"4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","",""-"4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","",""-"4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","",""-"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""-"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""--   * There is one CSV record per posting, with the parent transaction's-     fields repeated.-   * The "txnidx" (transaction index) field shows which postings belong-     to the same transaction.  (This number might change if transactions-     are reordered within the file, files are parsed/included in a-     different order, etc.)-   * The amount is separated into "commodity" (the symbol) and "amount"-     (numeric quantity) fields.-   * The numeric amount is repeated in either the "credit" or "debit"-     column, for convenience.  (Those names are not accurate in the-     accounting sense; it just puts negative amounts under credit and-     zero or greater amounts under debit.)---File: hledger.info,  Node: register,  Next: rewrite,  Prev: print,  Up: PART 4 COMMANDS--24.25 register-==============--(reg)--   Show postings and their running total.--   The register command displays matched postings, across all accounts,-in date order, with their running total or running historical balance.-(See also the 'aregister' command, which shows matched transactions in a-specific account.)--   register normally shows line per posting, but note that-multi-commodity amounts will occupy multiple lines (one line per-commodity).--   It is typically used with a query selecting a particular account, to-see that account's activity:--$ hledger register checking-2008/01/01 income               assets:bank:checking            $1           $1-2008/06/01 gift                 assets:bank:checking            $1           $2-2008/06/02 save                 assets:bank:checking           $-1           $1-2008/12/31 pay off              assets:bank:checking           $-1            0--   With '--date2', it shows and sorts by secondary date instead.--   For performance reasons, column widths are chosen based on the first-1000 lines; this means unusually wide values in later lines can cause-visual discontinuities as column widths are adjusted.  If you want to-ensure perfect alignment, at the cost of more time and memory, use the-'--align-all' flag.--   The '--historical'/'-H' flag adds the balance from any undisplayed-prior postings to the running total.  This is useful when you want to-see only recent activity, with a historically accurate running balance:--$ hledger register checking -b 2008/6 --historical-2008/06/01 gift                 assets:bank:checking            $1           $2-2008/06/02 save                 assets:bank:checking           $-1           $1-2008/12/31 pay off              assets:bank:checking           $-1            0--   The '--depth' option limits the amount of sub-account detail-displayed.--   The '--average'/'-A' flag shows the running average posting amount-instead of the running total (so, the final number displayed is the-average for the whole report period).  This flag implies '--empty' (see-below).  It is affected by '--historical'.  It works best when showing-just one account and one commodity.--   The '--related'/'-r' flag shows the _other_ postings in the-transactions of the postings which would normally be shown.--   The '--invert' flag negates all amounts.  For example, it can be used-on an income account where amounts are normally displayed as negative-numbers.  It's also useful to show postings on the checking account-together with the related account:--$ hledger register --related --invert assets:checking--   With a reporting interval, register shows summary postings, one per-interval, aggregating the postings to each account:--$ hledger register --monthly income-2008/01                 income:salary                          $-1          $-1-2008/06                 income:gifts                           $-1          $-2--   Periods with no activity, and summary postings with a zero amount,-are not shown by default; use the '--empty'/'-E' flag to see them:--$ hledger register --monthly income -E-2008/01                 income:salary                          $-1          $-1-2008/02                                                          0          $-1-2008/03                                                          0          $-1-2008/04                                                          0          $-1-2008/05                                                          0          $-1-2008/06                 income:gifts                           $-1          $-2-2008/07                                                          0          $-2-2008/08                                                          0          $-2-2008/09                                                          0          $-2-2008/10                                                          0          $-2-2008/11                                                          0          $-2-2008/12                                                          0          $-2--   Often, you'll want to see just one line per interval.  The '--depth'-option helps with this, causing subaccounts to be aggregated:--$ hledger register --monthly assets --depth 1h-2008/01                 assets                                  $1           $1-2008/06                 assets                                 $-1            0-2008/12                 assets                                 $-1          $-1--   Note when using report intervals, if you specify start/end dates-these will be adjusted outward if necessary to contain a whole number of-intervals.  This ensures that the first and last intervals are full-length and comparable to the others in the report.--   With '-m DESC'/'--match=DESC', register does a fuzzy search for one-recent posting whose description is most similar to DESC. DESC should-contain at least two characters.  If there is no similar-enough match,-no posting will be shown and the program exit code will be non-zero.--* Menu:--* Custom register output::---File: hledger.info,  Node: Custom register output,  Up: register--24.25.1 Custom register output---------------------------------register uses the full terminal width by default, except on windows.-You can override this by setting the 'COLUMNS' environment variable (not-a bash shell variable) or by using the '--width'/'-w' option.--   The description and account columns normally share the space equally-(about half of (width - 40) each).  You can adjust this by adding a-description width as part of -width's argument, comma-separated:-'--width W,D' .  Here's a diagram (won't display correctly in -help):--<--------------------------------- width (W) ---------------------------------->-date (10)  description (D)       account (W-41-D)     amount (12)   balance (12)-DDDDDDDDDD dddddddddddddddddddd  aaaaaaaaaaaaaaaaaaa  AAAAAAAAAAAA  AAAAAAAAAAAA--   and some examples:--$ hledger reg                     # use terminal width (or 80 on windows)-$ hledger reg -w 100              # use width 100-$ COLUMNS=100 hledger reg         # set with one-time environment variable-$ export COLUMNS=100; hledger reg # set till session end (or window resize)-$ hledger reg -w 100,40           # set overall width 100, description width 40-$ hledger reg -w $COLUMNS,40      # use terminal width, & description width 40--   This command also supports the output destination and output format-options The output formats supported are 'txt', 'csv', 'tsv', and-(experimental) 'json'.---File: hledger.info,  Node: rewrite,  Next: roi,  Prev: register,  Up: PART 4 COMMANDS--24.26 rewrite-=============--Print all transactions, rewriting the postings of matched transactions.-For now the only rewrite available is adding new postings, like print--auto.--   This is a start at a generic rewriter of transaction entries.  It-reads the default journal and prints the transactions, like print, but-adds one or more specified postings to any transactions matching QUERY.-The posting amounts can be fixed, or a multiplier of the existing-transaction's first posting amount.--   Examples:--$ hledger-rewrite.hs ^income --add-posting '(liabilities:tax)  *.33  ; income tax' --add-posting '(reserve:gifts)  $100'-$ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts)  *-1"'-$ hledger-rewrite.hs -f rewrites.hledger--   rewrites.hledger may consist of entries like:--= ^income amt:<0 date:2017-  (liabilities:tax)  *0.33  ; tax on income-  (reserve:grocery)  *0.25  ; reserve 25% for grocery-  (reserve:)  *0.25  ; reserve 25% for grocery--   Note the single quotes to protect the dollar sign from bash, and the-two spaces between account and amount.--   More:--$ hledger rewrite -- [QUERY]        --add-posting "ACCT  AMTEXPR" ...-$ hledger rewrite -- ^income        --add-posting '(liabilities:tax)  *.33'-$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts)  *-1"'-$ hledger rewrite -- ^income        --add-posting '(budget:foreign currency)  *0.25 JPY; diversify'--   Argument for '--add-posting' option is a usual posting of transaction-with an exception for amount specification.  More precisely, you can use-''*'' (star symbol) before the amount to indicate that that this is a-factor for an amount of original matched posting.  If the amount-includes a commodity name, the new posting amount will be in the new-commodity; otherwise, it will be in the matched posting amount's-commodity.--* Menu:--* Re-write rules in a file::-* Diff output format::-* rewrite vs print --auto::---File: hledger.info,  Node: Re-write rules in a file,  Next: Diff output format,  Up: rewrite--24.26.1 Re-write rules in a file-----------------------------------During the run this tool will execute so called "Automated Transactions"-found in any journal it process.  I.e instead of specifying this-operations in command line you can put them in a journal file.--$ rewrite-rules.journal--   Make contents look like this:--= ^income-    (liabilities:tax)  *.33--= expenses:gifts-    budget:gifts  *-1-    assets:budget  *1--   Note that ''='' (equality symbol) that is used instead of date in-transactions you usually write.  It indicates the query by which you-want to match the posting to add new ones.--$ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal--   This is something similar to the commands pipeline:--$ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax)  *.33' \-  | hledger rewrite -- -f - expenses:gifts      --add-posting 'budget:gifts  *-1'       \-                                                --add-posting 'assets:budget  *1'       \-  > rewritten-tidy-output.journal--   It is important to understand that relative order of such entries in-journal is important.  You can re-use result of previously added-postings.---File: hledger.info,  Node: Diff output format,  Next: rewrite vs print --auto,  Prev: Re-write rules in a file,  Up: rewrite--24.26.2 Diff output format-----------------------------To use this tool for batch modification of your journal files you may-find useful output in form of unified diff.--$ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax)  *.33'--   Output might look like:----- /tmp/examples/sample.journal-+++ /tmp/examples/sample.journal-@@ -18,3 +18,4 @@- 2008/01/01 income--    assets:bank:checking  $1-+    assets:bank:checking            $1-     income:salary-+    (liabilities:tax)                0-@@ -22,3 +23,4 @@- 2008/06/01 gift--    assets:bank:checking  $1-+    assets:bank:checking            $1-     income:gifts-+    (liabilities:tax)                0--   If you'll pass this through 'patch' tool you'll get transactions-containing the posting that matches your query be updated.  Note that-multiple files might be update according to list of input files-specified via '--file' options and 'include' directives inside of these-files.--   Be careful.  Whole transaction being re-formatted in a style of-output from 'hledger print'.--   See also:--   https://github.com/simonmichael/hledger/issues/99---File: hledger.info,  Node: rewrite vs print --auto,  Prev: Diff output format,  Up: rewrite--24.26.3 rewrite vs. print -auto----------------------------------This command predates print -auto, and currently does much the same-thing, but with these differences:--   * with multiple files, rewrite lets rules in any file affect all-     other files.  print -auto uses standard directive scoping; rules-     affect only child files.--   * rewrite's query limits which transactions can be rewritten; all are-     printed.  print -auto's query limits which transactions are-     printed.--   * rewrite applies rules specified on command line or in the journal.-     print -auto applies rules specified in the journal.---File: hledger.info,  Node: roi,  Next: stats,  Prev: rewrite,  Up: PART 4 COMMANDS--24.27 roi-=========--Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on-your investments.--   At a minimum, you need to supply a query (which could be just an-account name) to select your investment(s) with '--inv', and another-query to identify your profit and loss transactions with '--pnl'.--   If you do not record changes in the value of your investment-manually, or do not require computation of time-weighted return (TWR),-'--pnl' could be an empty query ('--pnl ""' or '--pnl STR' where 'STR'-does not match any of your accounts).--   This command will compute and display the internalized rate of return-(IRR, also known as money-weighted rate of return) and time-weighted-rate of return (TWR) for your investments for the time period requested.-IRR is always annualized due to the way it is computed, but TWR is-reported both as a rate over the chosen reporting period and as an-annual rate.--   Price directives will be taken into account if you supply appropriate-'--cost' or '--value' flags (see VALUATION).--   Note, in some cases this report can fail, for these reasons:--   * Error (NotBracketed): No solution for Internal Rate of Return-     (IRR). Possible causes: IRR is huge (>1000000%), balance of-     investment becomes negative at some point in time.-   * Error (SearchFailed): Failed to find solution for Internal Rate of-     Return (IRR). Either search does not converge to a solution, or-     converges too slowly.--   Examples:--   * Using roi to compute total return of investment in stocks:-     https://github.com/simonmichael/hledger/blob/master/examples/investing/roi-unrealised.ledger--   * Cookbook > Return on Investment: https://hledger.org/roi.html--* Menu:--* Spaces and special characters in --inv and --pnl::-* Semantics of --inv and --pnl::-* IRR and TWR explained::---File: hledger.info,  Node: Spaces and special characters in --inv and --pnl,  Next: Semantics of --inv and --pnl,  Up: roi--24.27.1 Spaces and special characters in '--inv' and-------------------------------------------------------'--pnl' Note that '--inv' and '--pnl''s argument is a query, and queries-could have several space-separated terms (see QUERIES).--   To indicate that all search terms form single command-line argument,-you will need to put them in quotes (see Special characters):--$ hledger roi --inv 'term1 term2 term3 ...'--   If any query terms contain spaces themselves, you will need an extra-level of nested quoting, eg:--$ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'"---File: hledger.info,  Node: Semantics of --inv and --pnl,  Next: IRR and TWR explained,  Prev: Spaces and special characters in --inv and --pnl,  Up: roi--24.27.2 Semantics of '--inv' and '--pnl'-------------------------------------------Query supplied to '--inv' has to match all transactions that are related-to your investment.  Transactions not matching '--inv' will be ignored.--   In these transactions, ROI will conside postings that match '--inv'-to be "investment postings" and other postings (not matching '--inv')-will be sorted into two categories: "cash flow" and "profit and loss",-as ROI needs to know which part of the investment value is your-contributions and which is due to the return on investment.--   * "Cash flow" is depositing or withdrawing money, buying or selling-     assets, or otherwise converting between your investment commodity-     and any other commodity.  Example:--     2019-01-01 Investing in Snake Oil-       assets:cash          -$100-       investment:snake oil-     -     2020-01-01 Selling my Snake Oil-       assets:cash           $10-       investment:snake oil  = 0--   * "Profit and loss" is change in the value of your investment:--     2019-06-01 Snake Oil falls in value-       investment:snake oil  = $57-       equity:unrealized profit or loss--   All non-investment postings are assumed to be "cash flow", unless-they match '--pnl' query.  Changes in value of your investment due to-"profit and loss" postings will be considered as part of your investment-return.--   Example: if you use '--inv snake --pnl equity:unrealized', then-postings in the example below would be classifed as:--2019-01-01 Snake Oil #1-  assets:cash          -$100   ; cash flow posting-  investment:snake oil         ; investment posting--2019-03-01 Snake Oil #2-  equity:unrealized pnl  -$100 ; profit and loss posting-  snake oil                    ; investment posting--2019-07-01 Snake Oil #3-  equity:unrealized pnl        ; profit and loss posting-  cash          -$100          ; cash flow posting-  snake oil     $50            ; investment posting---File: hledger.info,  Node: IRR and TWR explained,  Prev: Semantics of --inv and --pnl,  Up: roi--24.27.3 IRR and TWR explained--------------------------------"ROI" stands for "return on investment".  Traditionally this was-computed as a difference between current value of investment and its-initial value, expressed in percentage of the initial value.--   However, this approach is only practical in simple cases, where-investments receives no in-flows or out-flows of money, and where rate-of growth is fixed over time.  For more complex scenarios you need-different ways to compute rate of return, and this command implements-two of them: IRR and TWR.--   Internal rate of return, or "IRR" (also called "money-weighted rate-of return") takes into account effects of in-flows and out-flows, and-the time between them.  Investment at a particular fixed interest rate-is going to give you more interest than the same amount invested at the-same interest rate, but made later in time.  If you are withdrawing from-your investment, your future gains would be smaller (in absolute-numbers), and will be a smaller percentage of your initial investment,-so your IRR will be smaller.  And if you are adding to your investment,-you will receive bigger absolute gains, which will be a bigger-percentage of your initial investment, so your IRR will be larger.--   As mentioned before, in-flows and out-flows would be any cash that-you personally put in or withdraw, and for the "roi" command, these are-the postings that match the query in the'--inv' argument and NOT match-the query in the'--pnl' argument.--   If you manually record changes in the value of your investment as-transactions that balance them against "profit and loss" (or "unrealized-gains") account or use price directives, then in order for IRR to-compute the precise effect of your in-flows and out-flows on the rate of-return, you will need to record the value of your investement on or-close to the days when in- or out-flows occur.--   In technical terms, IRR uses the same approach as computation of net-present value, and tries to find a discount rate that makes net present-value of all the cash flows of your investment to add up to zero.  This-could be hard to wrap your head around, especially if you haven't done-discounted cash flow analysis before.  Implementation of IRR in hledger-should produce results that match the '=XIRR' formula in Excel.--   Second way to compute rate of return that 'roi' command implements is-called "time-weighted rate of return" or "TWR". Like IRR, it will-account for the effect of your in-flows and out-flows, but unlike IRR it-will try to compute the true rate of return of the underlying asset,-compensating for the effect that deposits and withdrawas have on the-apparent rate of growth of your investment.--   TWR represents your investment as an imaginary "unit fund" where-in-flows/ out-flows lead to buying or selling "units" of your investment-and changes in its value change the value of "investment unit".  Change-in "unit price" over the reporting period gives you rate of return of-your investment, and make TWR less sensitive than IRR to the effects of-cash in-flows and out-flows.--   References:--   * Explanation of rate of return-   * Explanation of IRR-   * Explanation of TWR-   * IRR vs TWR-   * Examples of computing IRR and TWR and discussion of the limitations-     of both metrics---File: hledger.info,  Node: stats,  Next: tags,  Prev: roi,  Up: PART 4 COMMANDS--24.28 stats-===========--Show journal and performance statistics.--   The stats command displays summary information for the whole journal,-or a matched part of it.  With a reporting interval, it shows a report-for each report period.--   At the end, it shows (in the terminal) the overall run time and-number of transactions processed per second.  Note these are approximate-and will vary based on machine, current load, data size, hledger-version, haskell lib versions, GHC version..  but they may be of-interest.  The 'stats' command's run time is similar to that of a-single-column balance report.--   Example:--$ hledger stats -f examples/1000x1000x10.journal-Main file                : /Users/simon/src/hledger/examples/1000x1000x10.journal-Included files           : -Transactions span        : 2000-01-01 to 2002-09-27 (1000 days)-Last transaction         : 2002-09-26 (6995 days ago)-Transactions             : 1000 (1.0 per day)-Transactions last 30 days: 0 (0.0 per day)-Transactions last 7 days : 0 (0.0 per day)-Payees/descriptions      : 1000-Accounts                 : 1000 (depth 10)-Commodities              : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z)-Market prices            : 1000 (A)--Run time                 : 0.12 s-Throughput               : 8342 txns/s--   This command supports the -o/-output-file option (but not--O/-output-format selection).---File: hledger.info,  Node: tags,  Next: test,  Prev: stats,  Up: PART 4 COMMANDS--24.29 tags-==========--List the tags used in the journal, or their values.--   This command lists the tag names used in the journal, whether on-transactions, postings, or account declarations.--   With a TAGREGEX argument, only tag names matching this regular-expression (case insensitive, infix matched) are shown.--   With QUERY arguments, only transactions and accounts matching this-query are considered.  If the query involves transaction fields (date:,-desc:, amt:, ...), the search is restricted to the matched transactions-and their accounts.--   With the -values flag, the tags' unique non-empty values are listed-instead.  With -E/-empty, blank/empty values are also shown.--   With -parsed, tags or values are shown in the order they were parsed,-with duplicates included.  (Except, tags from account declarations are-always shown first.)--   Tip: remember, accounts also acquire tags from their parents,-postings also acquire tags from their account and transaction,-transactions also acquire tags from their postings.---File: hledger.info,  Node: test,  Prev: tags,  Up: PART 4 COMMANDS--24.30 test-==========--Run built-in unit tests.--   This command runs the unit tests built in to hledger and hledger-lib,-printing the results on stdout.  If any test fails, the exit code will-be non-zero.--   This is mainly used by hledger developers, but you can also use it to-sanity-check the installed hledger executable on your platform.  All-tests are expected to pass - if you ever see a failure, please report as-a bug!--   This command also accepts tasty test runner options, written after a-- (double hyphen).  Eg to run only the tests in Hledger.Data.Amount,-with ANSI colour codes disabled:--$ hledger test -- -pData.Amount --color=never--   For help on these, see https://github.com/feuerbach/tasty#options-('-- --help' currently doesn't show them).---File: hledger.info,  Node: PART 5 COMMON TASKS,  Next: BUGS,  Prev: PART 4 COMMANDS,  Up: Top--25 PART 5: COMMON TASKS-***********************--Here are some quick examples of how to do some basic tasks with hledger.--* Menu:--* Getting help::-* Constructing command lines::-* Starting a journal file::-* Setting LEDGER_FILE::-* Setting opening balances::-* Recording transactions::-* Reconciling::-* Reporting::-* Migrating to a new file::---File: hledger.info,  Node: Getting help,  Next: Constructing command lines,  Up: PART 5 COMMON TASKS--25.1 Getting help-=================--Here's how to list commands and view options and command docs:--$ hledger                # show available commands-$ hledger --help         # show common options-$ hledger CMD --help     # show CMD's options, common options and CMD's documentation--   You can also view your hledger version's manual in several formats by-using the help command.  Eg:--$ hledger help           # show the hledger manual with info, man or $PAGER (best available)-$ hledger help journal   # show the journal topic in the hledger manual-$ hledger help --help    # find out more about the help command--   To view manuals and introductory docs on the web, visit-https://hledger.org.  Chat and mail list support and discussion archives-can be found at https://hledger.org/support.---File: hledger.info,  Node: Constructing command lines,  Next: Starting a journal file,  Prev: Getting help,  Up: PART 5 COMMON TASKS--25.2 Constructing command lines-===============================--hledger has a flexible command line interface.  We strive to keep it-simple and ergonomic, but if you run into one of the sharp edges-described in OPTIONS, here are some tips that might help:--   * command-specific options must go after the command (it's fine to-     put common options there too: 'hledger CMD OPTS ARGS')-   * running add-on executables directly simplifies command line parsing-     ('hledger-ui OPTS ARGS')-   * enclose "problematic" args in single quotes-   * if needed, also add a backslash to hide regular expression-     metacharacters from the shell-   * to see how a misbehaving command line is being parsed, add-     '--debug=2'.---File: hledger.info,  Node: Starting a journal file,  Next: Setting LEDGER_FILE,  Prev: Constructing command lines,  Up: PART 5 COMMON TASKS--25.3 Starting a journal file-============================--hledger looks for your accounting data in a journal file,-'$HOME/.hledger.journal' by default:--$ hledger stats-The hledger journal file "/Users/simon/.hledger.journal" was not found.-Please create it first, eg with "hledger add" or a text editor.-Or, specify an existing journal file with -f or LEDGER_FILE.--   You can override this by setting the 'LEDGER_FILE' environment-variable (see below).  It's a good practice to keep this important file-under version control, and to start a new file each year.  So you could-do something like this:--$ mkdir ~/finance-$ cd ~/finance-$ git init-Initialized empty Git repository in /Users/simon/finance/.git/-$ touch 2023.journal-$ echo "export LEDGER_FILE=$HOME/finance/2023.journal" >> ~/.profile-$ source ~/.profile-$ hledger stats-Main file                : /Users/simon/finance/2023.journal-Included files           : -Transactions span        :  to  (0 days)-Last transaction         : none-Transactions             : 0 (0.0 per day)-Transactions last 30 days: 0 (0.0 per day)-Transactions last 7 days : 0 (0.0 per day)-Payees/descriptions      : 0-Accounts                 : 0 (depth 0)-Commodities              : 0 ()-Market prices            : 0 ()---File: hledger.info,  Node: Setting LEDGER_FILE,  Next: Setting opening balances,  Prev: Starting a journal file,  Up: PART 5 COMMON TASKS--25.4 Setting LEDGER_FILE-========================--How to set 'LEDGER_FILE' permanently depends on your setup:--   On unix and mac, running these commands in the terminal will work for-many people; adapt as needed:--$ echo 'export LEDGER_FILE=~/finance/2023.journal' >> ~/.profile-$ source ~/.profile--   When correctly configured, in a new terminal window 'env | grep-LEDGER_FILE' will show your file, and so will 'hledger files'.--   On mac, this additional step might be helpful for GUI applications-(like Emacs started from the dock): add an entry to-'~/.MacOSX/environment.plist' like--{-  "LEDGER_FILE" : "~/finance/2023.journal"-}--   and then run 'killall Dock' in a terminal window (or restart the-machine).--   On Windows, see https://www.java.com/en/download/help/path.html, or-try running these commands in a powershell window (let us know if it-persists across a reboot, and if you need to be an Administrator):--> CD-> MKDIR finance-> SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal"---File: hledger.info,  Node: Setting opening balances,  Next: Recording transactions,  Prev: Setting LEDGER_FILE,  Up: PART 5 COMMON TASKS--25.5 Setting opening balances-=============================--Pick a starting date for which you can look up the balances of some-real-world assets (bank accounts, wallet..)  and liabilities (credit-cards..).--   To avoid a lot of data entry, you may want to start with just one or-two accounts, like your checking account or cash wallet; and pick a-recent starting date, like today or the start of the week.  You can-always come back later and add more accounts and older transactions, eg-going back to january 1st.--   Add an opening balances transaction to the journal, declaring the-balances on this date.  Here are two ways to do it:--   * The first way: open the journal in any text editor and save an-     entry like this:--     2023-01-01 * opening balances-         assets:bank:checking                $1000   = $1000-         assets:bank:savings                 $2000   = $2000-         assets:cash                          $100   = $100-         liabilities:creditcard               $-50   = $-50-         equity:opening/closing balances--     These are start-of-day balances, ie whatever was in the account at-     the end of the previous day.--     The * after the date is an optional status flag.  Here it means-     "cleared & confirmed".--     The currency symbols are optional, but usually a good idea as-     you'll be dealing with multiple currencies sooner or later.--     The = amounts are optional balance assertions, providing extra-     error checking.--   * The second way: run 'hledger add' and follow the prompts to record-     a similar transaction:--     $ hledger add-     Adding transactions to journal file /Users/simon/finance/2023.journal-     Any command line arguments will be used as defaults.-     Use tab key to complete, readline keys to edit, enter to accept defaults.-     An optional (CODE) may follow transaction dates.-     An optional ; COMMENT may follow descriptions or amounts.-     If you make a mistake, enter < at any prompt to go one step backward.-     To end a transaction, enter . when prompted.-     To quit, enter . at a date prompt or press control-d or control-c.-     Date [2023-02-07]: 2023-01-01-     Description: * opening balances-     Account 1: assets:bank:checking-     Amount  1: $1000-     Account 2: assets:bank:savings-     Amount  2 [$-1000]: $2000-     Account 3: assets:cash-     Amount  3 [$-3000]: $100-     Account 4: liabilities:creditcard-     Amount  4 [$-3100]: $-50-     Account 5: equity:opening/closing balances-     Amount  5 [$-3050]: -     Account 6 (or . or enter to finish this transaction): .-     2023-01-01 * opening balances-         assets:bank:checking                      $1000-         assets:bank:savings                       $2000-         assets:cash                                $100-         liabilities:creditcard                     $-50-         equity:opening/closing balances          $-3050-     -     Save this transaction to the journal ? [y]: -     Saved.-     Starting the next transaction (. or ctrl-D/ctrl-C to quit)-     Date [2023-01-01]: .--   If you're using version control, this could be a good time to commit-the journal.  Eg:--$ git commit -m 'initial balances' 2023.journal---File: hledger.info,  Node: Recording transactions,  Next: Reconciling,  Prev: Setting opening balances,  Up: PART 5 COMMON TASKS--25.6 Recording transactions-===========================--As you spend or receive money, you can record these transactions using-one of the methods above (text editor, hledger add) or by using the-hledger-iadd or hledger-web add-ons, or by using the import command to-convert CSV data downloaded from your bank.--   Here are some simple transactions, see the hledger_journal(5) manual-and hledger.org for more ideas:--2023/1/10 * gift received-  assets:cash   $20-  income:gifts--2023.1.12 * farmers market-  expenses:food    $13-  assets:cash--2023-01-15 paycheck-  income:salary-  assets:bank:checking    $1000---File: hledger.info,  Node: Reconciling,  Next: Reporting,  Prev: Recording transactions,  Up: PART 5 COMMON TASKS--25.7 Reconciling-================--Periodically you should reconcile - compare your hledger-reported-balances against external sources of truth, like bank statements or your-bank's website - to be sure that your ledger accurately represents the-real-world balances (and, that the real-world institutions have not made-a mistake!).  This gets easy and fast with (1) practice and (2)-frequency.  If you do it daily, it can take 2-10 minutes.  If you let it-pile up, expect it to take longer as you hunt down errors and-discrepancies.--   A typical workflow:--  1. Reconcile cash.  Count what's in your wallet.  Compare with what-     hledger reports ('hledger bal cash').  If they are different, try-     to remember the missing transaction, or look for the error in the-     already-recorded transactions.  A register report can be helpful-     ('hledger reg cash').  If you can't find the error, add an-     adjustment transaction.  Eg if you have $105 after the above, and-     can't explain the missing $2, it could be:--     2023-01-16 * adjust cash-         assets:cash    $-2 = $105-         expenses:misc--  2. Reconcile checking.  Log in to your bank's website.  Compare-     today's (cleared) balance with hledger's cleared balance ('hledger-     bal checking -C').  If they are different, track down the error or-     record the missing transaction(s) or add an adjustment transaction,-     similar to the above.  Unlike the cash case, you can usually-     compare the transaction history and running balance from your bank-     with the one reported by 'hledger reg checking -C'.  This will be-     easier if you generally record transaction dates quite similar to-     your bank's clearing dates.--  3. Repeat for other asset/liability accounts.--   Tip: instead of the register command, use hledger-ui to see a-live-updating register while you edit the journal: 'hledger-ui --watch---register checking -C'--   After reconciling, it could be a good time to mark the reconciled-transactions' status as "cleared and confirmed", if you want to track-that, by adding the '*' marker.  Eg in the paycheck transaction above,-insert '*' between '2023-01-15' and 'paycheck'--   If you're using version control, this can be another good time to-commit:--$ git commit -m 'txns' 2023.journal---File: hledger.info,  Node: Reporting,  Next: Migrating to a new file,  Prev: Reconciling,  Up: PART 5 COMMON TASKS--25.8 Reporting-==============--Here are some basic reports.--   Show all transactions:--$ hledger print-2023-01-01 * opening balances-    assets:bank:checking                      $1000-    assets:bank:savings                       $2000-    assets:cash                                $100-    liabilities:creditcard                     $-50-    equity:opening/closing balances          $-3050--2023-01-10 * gift received-    assets:cash              $20-    income:gifts--2023-01-12 * farmers market-    expenses:food             $13-    assets:cash--2023-01-15 * paycheck-    income:salary-    assets:bank:checking           $1000--2023-01-16 * adjust cash-    assets:cash               $-2 = $105-    expenses:misc--   Show account names, and their hierarchy:--$ hledger accounts --tree-assets-  bank-    checking-    savings-  cash-equity-  opening/closing balances-expenses-  food-  misc-income-  gifts-  salary-liabilities-  creditcard--   Show all account totals:--$ hledger balance-               $4105  assets-               $4000    bank-               $2000      checking-               $2000      savings-                $105    cash-              $-3050  equity:opening/closing balances-                 $15  expenses-                 $13    food-                  $2    misc-              $-1020  income-                $-20    gifts-              $-1000    salary-                $-50  liabilities:creditcard----------------------                   0--   Show only asset and liability balances, as a flat list, limited to-depth 2:--$ hledger bal assets liabilities -2-               $4000  assets:bank-                $105  assets:cash-                $-50  liabilities:creditcard----------------------               $4055--   Show the same thing without negative numbers, formatted as a simple-balance sheet:--$ hledger bs -2-Balance Sheet 2023-01-16--                        || 2023-01-16 -========================++============- Assets                 ||            -------------------------++------------- assets:bank            ||      $4000 - assets:cash            ||       $105 -------------------------++-------------                        ||      $4105 -========================++============- Liabilities            ||            -------------------------++------------- liabilities:creditcard ||        $50 -------------------------++-------------                        ||        $50 -========================++============- Net:                   ||      $4055 --   The final total is your "net worth" on the end date.  (Or use 'bse'-for a full balance sheet with equity.)--   Show income and expense totals, formatted as an income statement:--hledger is -Income Statement 2023-01-01-2023-01-16--               || 2023-01-01-2023-01-16 -===============++=======================- Revenues      ||                       ----------------++------------------------ income:gifts  ||                   $20 - income:salary ||                 $1000 ----------------++------------------------               ||                 $1020 -===============++=======================- Expenses      ||                       ----------------++------------------------ expenses:food ||                   $13 - expenses:misc ||                    $2 ----------------++------------------------               ||                   $15 -===============++=======================- Net:          ||                 $1005 --   The final total is your net income during this period.--   Show transactions affecting your wallet, with running total:--$ hledger register cash-2023-01-01 opening balances     assets:cash                   $100          $100-2023-01-10 gift received        assets:cash                    $20          $120-2023-01-12 farmers market       assets:cash                   $-13          $107-2023-01-16 adjust cash          assets:cash                    $-2          $105--   Show weekly posting counts as a bar chart:--$ hledger activity -W-2019-12-30 *****-2023-01-06 ****-2023-01-13 ****---File: hledger.info,  Node: Migrating to a new file,  Prev: Reporting,  Up: PART 5 COMMON TASKS--25.9 Migrating to a new file-============================--At the end of the year, you may want to continue your journal in a new-file, so that old transactions don't slow down or clutter your reports,-and to help ensure the integrity of your accounting history.  See the-close command.--   If using version control, don't forget to 'git add' the new file.---File: hledger.info,  Node: BUGS,  Prev: PART 5 COMMON TASKS,  Up: Top--26 BUGS-*******--We welcome bug reports in the hledger issue tracker (shortcut:-http://bugs.hledger.org), or on the #hledger chat or hledger mail list-(https://hledger.org/support).--   Some known issues and limitations:--   The need to precede add-on command options with '--' when invoked-from hledger is awkward.  (See Command options, Constructing command-lines.)--   A UTF-8-aware system locale must be configured to work with non-ascii-data.  (See Unicode characters, Troubleshooting.)--   On Microsoft Windows, depending whether you are running in a CMD-window or a Cygwin/MSYS/Mintty window and how you installed hledger,-non-ascii characters and colours may not be supported, and the tab key-may not be supported by 'hledger add'.  (Running in a WSL window should-resolve these.)--   When processing large data files, hledger uses more memory than-Ledger.--* Menu:--* Troubleshooting::---File: hledger.info,  Node: Troubleshooting,  Up: BUGS--26.1 Troubleshooting-====================--Here are some common issues you might encounter when you run hledger,-and how to resolve them (and remember also you can usually get quick-Support):--   *PATH issues: I get an error like "No command 'hledger' found"*-Depending how you installed hledger, the executables may not be in your-shell's PATH. Eg on unix systems, stack installs hledger in-'~/.local/bin' and cabal installs it in '~/.cabal/bin'.  You may need to-add one of these directories to your shell's PATH, and/or open a new-terminal window.--   *LEDGER_FILE issues: I configured LEDGER_FILE but hledger is not-using it*--   * 'LEDGER_FILE' should be a real environment variable, not just a-     shell variable.  Eg on unix, the command 'env | grep LEDGER_FILE'-     should show it.  You may need to use 'export' (see-     https://stackoverflow.com/a/7411509).-   * You may need to force your shell to see the new configuration.  A-     simple way is to close your terminal window and open a new one.--   *LANG issues: I get errors like "Illegal byte sequence" or "Invalid-or incomplete multibyte or wide character" or "commitAndReleaseBuffer:-invalid argument (invalid character)"*-Programs compiled with GHC (hledger, haskell build tools, etc.)  need-the system locale to be UTF-8-aware, or they will fail when they-encounter non-ascii characters.  To fix it, set the LANG environment-variable to a locale which supports UTF-8 and which is installed on your-system.--   On unix, 'locale -a' lists the installed locales.  Look for one which-mentions 'utf8', 'UTF-8' or similar.  Some examples: 'C.UTF-8',-'en_US.utf-8', 'fr_FR.utf8'.  If necessary, use your system package-manager to install one.  Then select it by setting the 'LANG'-environment variable.  Note, exact spelling and capitalisation of the-locale name may be important: Here's one common way to configure this-permanently for your shell:--$ echo "export LANG=en_US.utf8" >>~/.profile-# close and re-open terminal window--   If you are using Nix (not NixOS) for GHC and Hledger, you might need-to set the 'LOCALE_ARCHIVE' variable:--$ echo "export LOCALE_ARCHIVE=${glibcLocales}/lib/locale/locale-archive" >>~/.profile-# close and re-open terminal window--   *COMPATIBILITY ISSUES: hledger gives an error with my Ledger file*-Not all of Ledger's journal file syntax or feature set is supported.-See hledger and Ledger for full details.---Tag Table:-Node: Top210-Node: PART 1 USER INTERFACE3820-Ref: #part-1-user-interface3959-Node: Input3959-Ref: #input4069-Node: Data formats5018-Ref: #data-formats5131-Node: Standard input6493-Ref: #standard-input6633-Node: Multiple files6860-Ref: #multiple-files6999-Node: Strict mode7597-Ref: #strict-mode7707-Node: Commands8431-Ref: #commands8533-Node: Add-on commands9600-Ref: #add-on-commands9702-Node: Options10818-Ref: #options10930-Node: General help options11258-Ref: #general-help-options11404-Node: General input options11686-Ref: #general-input-options11868-Node: General reporting options12570-Ref: #general-reporting-options12731-Node: Command line tips16121-Ref: #command-line-tips16251-Node: Option repetition16510-Ref: #option-repetition16654-Node: Special characters16758-Ref: #special-characters16931-Node: Single escaping shell metacharacters17094-Ref: #single-escaping-shell-metacharacters17335-Node: Double escaping regular expression metacharacters17938-Ref: #double-escaping-regular-expression-metacharacters18249-Node: Triple escaping for add-on commands18775-Ref: #triple-escaping-for-add-on-commands19035-Node: Less escaping19679-Ref: #less-escaping19833-Node: Unicode characters20157-Ref: #unicode-characters20332-Node: Regular expressions21744-Ref: #regular-expressions21917-Node: hledger's regular expressions25013-Ref: #hledgers-regular-expressions25172-Node: Argument files26558-Ref: #argument-files26694-Node: Output27191-Ref: #output27303-Node: Output destination27430-Ref: #output-destination27561-Node: Output format27986-Ref: #output-format28132-Node: CSV output29729-Ref: #csv-output29845-Node: HTML output29948-Ref: #html-output30086-Node: JSON output30180-Ref: #json-output30318-Node: SQL output31240-Ref: #sql-output31356-Node: Commodity styles32091-Ref: #commodity-styles32231-Node: Colour32830-Ref: #colour32948-Node: Box-drawing33352-Ref: #box-drawing33470-Node: Paging33760-Ref: #paging33874-Node: Debug output34827-Ref: #debug-output34933-Node: Environment35596-Ref: #environment35720-Node: PART 2 DATA FORMATS36264-Ref: #part-2-data-formats36407-Node: Journal36407-Ref: #journal36516-Node: Journal cheatsheet37173-Ref: #journal-cheatsheet37312-Node: About journal format41297-Ref: #about-journal-format41457-Node: Comments43073-Ref: #comments43203-Node: Transactions44019-Ref: #transactions44142-Node: Dates45156-Ref: #dates45263-Node: Simple dates45308-Ref: #simple-dates45424-Node: Posting dates45924-Ref: #posting-dates46042-Node: Status47011-Ref: #status47112-Node: Code48820-Ref: #code48923-Node: Description49155-Ref: #description49286-Node: Payee and note49606-Ref: #payee-and-note49712-Node: Transaction comments50047-Ref: #transaction-comments50200-Node: Postings50563-Ref: #postings50696-Node: Account names51691-Ref: #account-names51821-Node: Amounts53495-Ref: #amounts53610-Node: Decimal marks digit group marks54595-Ref: #decimal-marks-digit-group-marks54770-Node: Commodity55629-Ref: #commodity55816-Node: Directives influencing number parsing and display56768-Ref: #directives-influencing-number-parsing-and-display57027-Node: Commodity display style57479-Ref: #commodity-display-style57685-Node: Rounding59095-Ref: #rounding59213-Node: Costs59663-Ref: #costs59779-Node: Other cost/lot notations61975-Ref: #other-costlot-notations62107-Node: Balance assertions64696-Ref: #balance-assertions64847-Node: Assertions and ordering65930-Ref: #assertions-and-ordering66119-Node: Assertions and multiple included files66819-Ref: #assertions-and-multiple-included-files67079-Node: Assertions and multiple -f files67579-Ref: #assertions-and-multiple--f-files67830-Node: Assertions and commodities68227-Ref: #assertions-and-commodities68449-Node: Assertions and prices69629-Ref: #assertions-and-prices69835-Node: Assertions and subaccounts70262-Ref: #assertions-and-subaccounts70483-Node: Assertions and virtual postings70807-Ref: #assertions-and-virtual-postings71045-Node: Assertions and auto postings71177-Ref: #assertions-and-auto-postings71407-Node: Assertions and precision72052-Ref: #assertions-and-precision72234-Node: Posting comments72501-Ref: #posting-comments72647-Node: Tags73024-Ref: #tags73138-Node: Tag values74331-Ref: #tag-values74420-Node: Directives75179-Ref: #directives75306-Node: Directives and multiple files76636-Ref: #directives-and-multiple-files76814-Node: Directive effects77581-Ref: #directive-effects77735-Node: account directive80748-Ref: #account-directive80904-Node: Account comments82302-Ref: #account-comments82452-Node: Account subdirectives82960-Ref: #account-subdirectives83151-Node: Account error checking83293-Ref: #account-error-checking83491-Node: Account display order84680-Ref: #account-display-order84868-Node: Account types85969-Ref: #account-types86110-Node: alias directive89737-Ref: #alias-directive89898-Node: Basic aliases90948-Ref: #basic-aliases91079-Node: Regex aliases91823-Ref: #regex-aliases91980-Node: Combining aliases92870-Ref: #combining-aliases93048-Node: Aliases and multiple files94324-Ref: #aliases-and-multiple-files94528-Node: end aliases directive95107-Ref: #end-aliases-directive95326-Node: Aliases can generate bad account names95475-Ref: #aliases-can-generate-bad-account-names95723-Node: Aliases and account types96308-Ref: #aliases-and-account-types96500-Node: commodity directive97196-Ref: #commodity-directive97370-Node: Commodity directive syntax98555-Ref: #commodity-directive-syntax98740-Node: Commodity error checking100119-Ref: #commodity-error-checking100300-Node: decimal-mark directive100594-Ref: #decimal-mark-directive100776-Node: include directive101173-Ref: #include-directive101337-Node: P directive102249-Ref: #p-directive102394-Node: payee directive103283-Ref: #payee-directive103432-Node: tag directive103748-Ref: #tag-directive103903-Node: Periodic transactions104371-Ref: #periodic-transactions104536-Node: Periodic rule syntax106242-Ref: #periodic-rule-syntax106420-Node: Periodic rules and relative dates107065-Ref: #periodic-rules-and-relative-dates107331-Node: Two spaces between period expression and description!107842-Ref: #two-spaces-between-period-expression-and-description108119-Node: Auto postings108803-Ref: #auto-postings108951-Node: Auto postings and multiple files111388-Ref: #auto-postings-and-multiple-files111552-Node: Auto postings and dates111953-Ref: #auto-postings-and-dates112201-Node: Auto postings and transaction balancing / inferred amounts / balance assertions112376-Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions112732-Node: Auto posting tags113235-Ref: #auto-posting-tags113517-Node: Auto postings on forecast transactions only114153-Ref: #auto-postings-on-forecast-transactions-only114399-Node: Other syntax114646-Ref: #other-syntax114762-Node: Balance assignments115389-Ref: #balance-assignments115545-Node: Balance assignments and prices116918-Ref: #balance-assignments-and-prices117133-Node: Balance assignments and multiple files117344-Ref: #balance-assignments-and-multiple-files117575-Node: Bracketed posting dates117768-Ref: #bracketed-posting-dates117952-Node: D directive118466-Ref: #d-directive118634-Node: apply account directive120234-Ref: #apply-account-directive120414-Node: Y directive121101-Ref: #y-directive121261-Node: Secondary dates122089-Ref: #secondary-dates122243-Node: Star comments123057-Ref: #star-comments123217-Node: Valuation expressions123749-Ref: #valuation-expressions123926-Node: Virtual postings124048-Ref: #virtual-postings124225-Node: Other Ledger directives125662-Ref: #other-ledger-directives125825-Node: CSV126391-Ref: #csv126484-Node: CSV rules cheatsheet128564-Ref: #csv-rules-cheatsheet128693-Node: source130491-Ref: #source130614-Node: separator131494-Ref: #separator131607-Node: skip132147-Ref: #skip132255-Node: date-format132799-Ref: #date-format132920-Node: timezone133644-Ref: #timezone133767-Node: newest-first134772-Ref: #newest-first134910-Node: intra-day-reversed135487-Ref: #intra-day-reversed135641-Node: decimal-mark136089-Ref: #decimal-mark136230-Node: fields list136569-Ref: #fields-list136708-Node: Field assignment138379-Ref: #field-assignment138523-Node: Field names139600-Ref: #field-names139731-Node: date field140934-Ref: #date-field141052-Node: date2 field141100-Ref: #date2-field141241-Node: status field141297-Ref: #status-field141440-Node: code field141489-Ref: #code-field141634-Node: description field141679-Ref: #description-field141839-Node: comment field141898-Ref: #comment-field142053-Node: account field142346-Ref: #account-field142496-Node: amount field143066-Ref: #amount-field143215-Node: currency field145907-Ref: #currency-field146060-Node: balance field146317-Ref: #balance-field146449-Node: if block146821-Ref: #if-block146942-Node: Matchers148350-Ref: #matchers148464-Node: Match groups150048-Ref: #match-groups150149-Node: if table150896-Ref: #if-table151018-Node: balance-type152580-Ref: #balance-type152709-Node: include153409-Ref: #include153536-Node: Working with CSV153980-Ref: #working-with-csv154127-Node: Rapid feedback154534-Ref: #rapid-feedback154667-Node: Valid CSV155119-Ref: #valid-csv155265-Node: File Extension155997-Ref: #file-extension156170-Node: Reading CSV from standard input156734-Ref: #reading-csv-from-standard-input156958-Node: Reading multiple CSV files157122-Ref: #reading-multiple-csv-files157353-Node: Reading files specified by rule157594-Ref: #reading-files-specified-by-rule157822-Node: Valid transactions158993-Ref: #valid-transactions159192-Node: Deduplicating importing159820-Ref: #deduplicating-importing160015-Node: Setting amounts161051-Ref: #setting-amounts161222-Node: Amount signs163580-Ref: #amount-signs163750-Node: Setting currency/commodity164647-Ref: #setting-currencycommodity164851-Node: Amount decimal places166025-Ref: #amount-decimal-places166231-Node: Referencing other fields166543-Ref: #referencing-other-fields166756-Node: How CSV rules are evaluated167653-Ref: #how-csv-rules-are-evaluated167870-Node: Well factored rules169323-Ref: #well-factored-rules169491-Node: CSV rules examples169815-Ref: #csv-rules-examples169950-Node: Bank of Ireland170015-Ref: #bank-of-ireland170152-Node: Coinbase171614-Ref: #coinbase171752-Node: Amazon172799-Ref: #amazon172924-Node: Paypal174643-Ref: #paypal174751-Node: Timeclock182395-Ref: #timeclock182500-Node: Timedot184678-Ref: #timedot184801-Node: Timedot examples187906-Ref: #timedot-examples188012-Node: PART 3 REPORTING CONCEPTS190183-Ref: #part-3-reporting-concepts190365-Node: Amount formatting parseability190365-Ref: #amount-formatting-parseability190562-Node: Time periods192767-Ref: #time-periods192906-Node: Report start & end date193024-Ref: #report-start-end-date193176-Node: Smart dates194835-Ref: #smart-dates194988-Node: Report intervals196856-Ref: #report-intervals197011-Node: Date adjustment197429-Ref: #date-adjustment197589-Node: Period expressions198440-Ref: #period-expressions198581-Node: Period expressions with a report interval200345-Ref: #period-expressions-with-a-report-interval200579-Node: More complex report intervals200793-Ref: #more-complex-report-intervals201038-Node: Multiple weekday intervals202839-Ref: #multiple-weekday-intervals203028-Node: Depth203850-Ref: #depth203952-Node: Queries204248-Ref: #queries204350-Node: Query types205475-Ref: #query-types205596-Node: Combining query terms208932-Ref: #combining-query-terms209109-Node: Queries and command options210377-Ref: #queries-and-command-options210576-Node: Queries and valuation210825-Ref: #queries-and-valuation211020-Node: Querying with account aliases211249-Ref: #querying-with-account-aliases211460-Node: Querying with cost or value211590-Ref: #querying-with-cost-or-value211767-Node: Pivoting212068-Ref: #pivoting212182-Node: Generating data213959-Ref: #generating-data214091-Node: Forecasting215674-Ref: #forecasting215799-Node: --forecast216330-Ref: #forecast216461-Node: Inspecting forecast transactions217507-Ref: #inspecting-forecast-transactions217709-Node: Forecast reports218839-Ref: #forecast-reports219012-Node: Forecast tags219948-Ref: #forecast-tags220108-Node: Forecast period in detail220568-Ref: #forecast-period-in-detail220762-Node: Forecast troubleshooting221656-Ref: #forecast-troubleshooting221824-Node: Budgeting222727-Ref: #budgeting222847-Node: Cost reporting223284-Ref: #cost-reporting223418-Node: Recording costs224079-Ref: #recording-costs224215-Node: Reporting at cost225806-Ref: #reporting-at-cost225981-Node: Equity conversion postings226571-Ref: #equity-conversion-postings226785-Node: Inferring equity conversion postings229216-Ref: #inferring-equity-conversion-postings229479-Node: Combining costs and equity conversion postings230231-Ref: #combining-costs-and-equity-conversion-postings230541-Node: Requirements for detecting equity conversion postings231529-Ref: #requirements-for-detecting-equity-conversion-postings231851-Node: Infer cost and equity by default ?233051-Ref: #infer-cost-and-equity-by-default233280-Node: Value reporting233488-Ref: #value-reporting233630-Node: -V Value234404-Ref: #v-value234536-Node: -X Value in specified commodity234731-Ref: #x-value-in-specified-commodity234932-Node: Valuation date235081-Ref: #valuation-date235258-Node: Finding market price236041-Ref: #finding-market-price236252-Node: --infer-market-prices market prices from transactions237421-Ref: #infer-market-prices-market-prices-from-transactions237703-Node: Valuation commodity240465-Ref: #valuation-commodity240684-Node: Simple valuation examples241897-Ref: #simple-valuation-examples242101-Node: --value Flexible valuation242760-Ref: #value-flexible-valuation242970-Node: More valuation examples244614-Ref: #more-valuation-examples244829-Node: Interaction of valuation and queries246099-Ref: #interaction-of-valuation-and-queries246346-Node: Effect of valuation on reports246818-Ref: #effect-of-valuation-on-reports247021-Node: PART 4 COMMANDS254718-Ref: #part-4-commands254867-Node: Commands overview255246-Ref: #commands-overview255380-Node: DATA ENTRY255559-Ref: #data-entry255683-Node: DATA CREATION255882-Ref: #data-creation256036-Node: DATA MANAGEMENT256154-Ref: #data-management256319-Node: REPORTS FINANCIAL256440-Ref: #reports-financial256615-Node: REPORTS VERSATILE256920-Ref: #reports-versatile257093-Node: REPORTS BASIC257346-Ref: #reports-basic257498-Node: HELP258007-Ref: #help258129-Node: ADD-ONS258239-Ref: #add-ons258345-Node: accounts258924-Ref: #accounts259057-Node: activity260944-Ref: #activity261063-Node: add261437-Ref: #add261547-Node: aregister264358-Ref: #aregister264479-Node: aregister and posting dates267367-Ref: #aregister-and-posting-dates267512-Node: balance268268-Ref: #balance268394-Node: balance features269379-Ref: #balance-features269519-Node: Simple balance report271485-Ref: #simple-balance-report271670-Node: Balance report line format273295-Ref: #balance-report-line-format273497-Node: Filtered balance report275655-Ref: #filtered-balance-report275847-Node: List or tree mode276174-Ref: #list-or-tree-mode276342-Node: Depth limiting277687-Ref: #depth-limiting277853-Node: Dropping top-level accounts278454-Ref: #dropping-top-level-accounts278654-Node: Showing declared accounts278964-Ref: #showing-declared-accounts279163-Node: Sorting by amount279694-Ref: #sorting-by-amount279861-Node: Percentages280531-Ref: #percentages280690-Node: Multi-period balance report281238-Ref: #multi-period-balance-report281438-Node: Balance change end balance283713-Ref: #balance-change-end-balance283922-Node: Balance report types285350-Ref: #balance-report-types285531-Node: Calculation type286029-Ref: #calculation-type286184-Node: Accumulation type286733-Ref: #accumulation-type286913-Node: Valuation type287815-Ref: #valuation-type288003-Node: Combining balance report types289004-Ref: #combining-balance-report-types289198-Node: Budget report291036-Ref: #budget-report291198-Node: Budget report start date296852-Ref: #budget-report-start-date297030-Node: Budgets and subaccounts298362-Ref: #budgets-and-subaccounts298569-Node: Selecting budget goals302009-Ref: #selecting-budget-goals302208-Node: Budget vs forecast303243-Ref: #budget-vs-forecast303402-Node: Balance report layout305032-Ref: #balance-report-layout305212-Node: Useful balance reports313397-Ref: #useful-balance-reports313557-Node: balancesheet314642-Ref: #balancesheet314787-Node: balancesheetequity316114-Ref: #balancesheetequity316272-Node: cashflow317668-Ref: #cashflow317799-Node: check319234-Ref: #check319348-Node: Default checks320152-Ref: #default-checks320278-Node: Strict checks320775-Ref: #strict-checks320920-Node: Other checks321400-Ref: #other-checks321542-Node: Custom checks322075-Ref: #custom-checks322232-Node: More about specific checks322649-Ref: #more-about-specific-checks322811-Node: close323517-Ref: #close323628-Node: close and balance assertions327093-Ref: #close-and-balance-assertions327271-Node: Example retain earnings328422-Ref: #example-retain-earnings328639-Node: Example migrate balances to a new file329071-Ref: #example-migrate-balances-to-a-new-file329336-Node: Example excluding closing/opening transactions329912-Ref: #example-excluding-closingopening-transactions330161-Node: codes331379-Ref: #codes331496-Node: commodities332360-Ref: #commodities332488-Node: demo332558-Ref: #demo332679-Node: descriptions333595-Ref: #descriptions333725-Node: diff334016-Ref: #diff334131-Node: files335173-Ref: #files335282-Node: help335423-Ref: #help-1335532-Node: import336905-Ref: #import337028-Node: Deduplication338136-Ref: #deduplication338261-Node: Import testing340280-Ref: #import-testing340445-Node: Importing balance assignments341288-Ref: #importing-balance-assignments341494-Node: Commodity display styles342143-Ref: #commodity-display-styles342316-Node: incomestatement342445-Ref: #incomestatement342587-Node: notes343915-Ref: #notes344037-Node: payees344399-Ref: #payees344514-Node: prices345033-Ref: #prices345148-Node: print345801-Ref: #print345916-Node: print explicitness346892-Ref: #print-explicitness347035-Node: print amount style347814-Ref: #print-amount-style347984-Node: print parseability349036-Ref: #print-parseability349208-Node: print other features349957-Ref: #print-other-features350136-Node: print output format350657-Ref: #print-output-format350805-Node: register353924-Ref: #register354046-Node: Custom register output359077-Ref: #custom-register-output359208-Node: rewrite360552-Ref: #rewrite360670-Node: Re-write rules in a file362568-Ref: #re-write-rules-in-a-file362731-Node: Diff output format363880-Ref: #diff-output-format364063-Node: rewrite vs print --auto365155-Ref: #rewrite-vs.-print---auto365315-Node: roi365871-Ref: #roi365978-Node: Spaces and special characters in --inv and --pnl367790-Ref: #spaces-and-special-characters-in---inv-and---pnl368030-Node: Semantics of --inv and --pnl368518-Ref: #semantics-of---inv-and---pnl368757-Node: IRR and TWR explained370607-Ref: #irr-and-twr-explained370767-Node: stats374020-Ref: #stats374128-Node: tags375515-Ref: #tags-1375622-Node: test376631-Ref: #test376724-Node: PART 5 COMMON TASKS377466-Ref: #part-5-common-tasks377612-Node: Getting help377910-Ref: #getting-help378051-Node: Constructing command lines378811-Ref: #constructing-command-lines379012-Node: Starting a journal file379669-Ref: #starting-a-journal-file379871-Node: Setting LEDGER_FILE381073-Ref: #setting-ledger_file381265-Node: Setting opening balances382222-Ref: #setting-opening-balances382423-Node: Recording transactions385564-Ref: #recording-transactions385753-Node: Reconciling386309-Ref: #reconciling386461-Node: Reporting388718-Ref: #reporting388867-Node: Migrating to a new file392852-Ref: #migrating-to-a-new-file393009-Node: BUGS393308-Ref: #bugs393398-Node: Troubleshooting394277-Ref: #troubleshooting394377+   This manual is for hledger's command line interface, version 1.32.1.+It also describes the common options, file formats and concepts used by+all hledger programs.  It might accidentally teach you some+bookkeeping/accounting as well!  You don't need to know everything in+here to use hledger productively, but when you have a question about+functionality, this doc should answer it.  It is detailed, so do skip+ahead or skim when needed.  You can read it on hledger.org, or as an+info manual or man page on your system.  You can also get it from+hledger itself with+'hledger --man', 'hledger --info' or 'hledger help [TOPIC]'.++   The main function of the hledger CLI is to read plain text files+describing financial transactions, crunch the numbers, and print a+useful report on the terminal (or save it as HTML, CSV, JSON or SQL).+Many reports are available, as subcommands.  hledger will also detect+other 'hledger-*' executables as extra subcommands.++   hledger usually reads from (and appends to) a journal file specified+by the 'LEDGER_FILE' environment variable (defaulting to+'$HOME/.hledger.journal'); or you can specify files with '-f' options.+It can also read timeclock files, timedot files, or any CSV/SSV/TSV file+with a date field.++   Here is a small journal file describing one transaction:++2015-10-16 bought food+  expenses:food          $10+  assets:cash++   Transactions are dated movements of money (etc.)  between two or more+_accounts_: bank accounts, your wallet, revenue/expense categories,+people, etc.  You can choose any account names you wish, using ':' to+indicate subaccounts.  There must be at least two spaces between account+name and amount.  Positive amounts are inflow to that account (_debit_),+negatives are outflow from it (_credit_).  (Some reports show revenue,+liability and equity account balances as negative numbers as a result;+this is normal.)++   hledger's add command can help you add transactions, or you can+install other data entry UIs like hledger-web or hledger-iadd.  For more+extensive/efficient changes, use a text editor: Emacs + ledger-mode, VIM++ vim-ledger, or VS Code + hledger-vscode are some good choices (see+https://hledger.org/editors.html).++   To get started, run 'hledger add' and follow the prompts, or save+some entries like the above in '$HOME/.hledger.journal', then try+commands like:+'hledger print -x'+'hledger aregister assets'+'hledger balance'+'hledger balancesheet'+'hledger incomestatement'.+Run 'hledger' to list the commands.  See also the "Starting a journal+file" and "Setting opening balances" sections in PART 5: COMMON TASKS.++* Menu:++* PART 1 USER INTERFACE::+* Input::+* Commands::+* Options::+* Command line tips::+* Output::+* Environment::+* PART 2 DATA FORMATS::+* Journal::+* CSV::+* Timeclock::+* Timedot::+* PART 3 REPORTING CONCEPTS::+* Amount formatting parseability::+* Time periods::+* Depth::+* Queries::+* Pivoting::+* Generating data::+* Forecasting::+* Budgeting::+* Cost reporting::+* Value reporting::+* PART 4 COMMANDS::+* PART 5 COMMON TASKS::+* BUGS::+++File: hledger.info,  Node: PART 1 USER INTERFACE,  Next: Input,  Prev: Top,  Up: Top++1 PART 1: USER INTERFACE+************************+++File: hledger.info,  Node: Input,  Next: Commands,  Prev: PART 1 USER INTERFACE,  Up: Top++2 Input+*******++hledger reads one or more data files, each time you run it.  You can+specify a file with '-f', like so++$ hledger -f FILE print++   Files are most often in hledger's journal format, with the '.journal'+file extension ('.hledger' or '.j' also work); these files describe+transactions, like an accounting general journal.++   When no file is specified, hledger looks for '.hledger.journal' in+your home directory.++   But most people prefer to keep financial files in a dedicated folder,+perhaps with version control.  Also, starting a new journal file each+year is common (it's not required, but helps keep things fast and+organised).  So we usually configure a different journal file, by+setting the 'LEDGER_FILE' environment variable, to something like+'~/finance/2023.journal'.  For more about how to do that on your system,+see Common tasks > Setting LEDGER_FILE.++* Menu:++* Data formats::+* Standard input::+* Multiple files::+* Strict mode::+++File: hledger.info,  Node: Data formats,  Next: Standard input,  Up: Input++2.1 Data formats+================++Usually the data file is in hledger's journal format, but it can be in+any of the supported file formats, which currently are:++Reader:       Reads:                          Used for file extensions:+----------------------------------------------------------------------------+'journal'     hledger journal files and       '.journal' '.j' '.hledger'+              some Ledger journals, for       '.ledger'+              transactions+'timeclock'   timeclock files, for precise    '.timeclock'+              time logging+'timedot'     timedot files, for              '.timedot'+              approximate time logging+'csv'         CSV/SSV/TSV/character-separated '.csv' '.ssv' '.tsv'+              values, for data import         '.csv.rules' '.ssv.rules'+                                              '.tsv.rules'++   These formats are described in more detail below.++   hledger detects the format automatically based on the file extensions+shown above.  If it can't recognise the file extension, it assumes+'journal' format.  So for non-journal files, it's important to use a+recognised file extension, so as to either read successfully or to show+relevant error messages.++   You can also force a specific reader/format by prefixing the file+path with the format and a colon.  Eg, to read a .dat file as csv+format:++$ hledger -f csv:/some/csv-file.dat stats+++File: hledger.info,  Node: Standard input,  Next: Multiple files,  Prev: Data formats,  Up: Input++2.2 Standard input+==================++The file name '-' means standard input:++$ cat FILE | hledger -f- print++   If reading non-journal data in this way, you'll need to add a file+format prefix, like:++$ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:-+++File: hledger.info,  Node: Multiple files,  Next: Strict mode,  Prev: Standard input,  Up: Input++2.3 Multiple files+==================++You can specify multiple '-f' options, to read multiple files as one big+journal.  When doing this, note that certain features (described below)+will be affected:++   * Balance assertions will not see the effect of transactions in+     previous files.  (Usually this doesn't matter as each file will set+     the corresponding opening balances.)+   * Some directives will not affect previous or subsequent files.++   If needed, you can work around these by using a single parent file+which includes the others, or concatenating the files into one, eg: 'cat+a.journal b.journal | hledger -f- CMD'.+++File: hledger.info,  Node: Strict mode,  Prev: Multiple files,  Up: Input++2.4 Strict mode+===============++hledger checks input files for valid data.  By default, the most+important errors are detected, while still accepting easy journal files+without a lot of declarations:++   * Are the input files parseable, with valid syntax ?+   * Are all transactions balanced ?+   * Do all balance assertions pass ?++   With the '-s'/'--strict' flag, additional checks are performed:++   * Are all accounts posted to, declared with an 'account' directive ?+     (Account error checking)+   * Are all commodities declared with a 'commodity' directive ?+     (Commodity error checking)+   * Are all commodity conversions declared explicitly ?++   You can use the check command to run individual checks - the ones+listed above and some more.+++File: hledger.info,  Node: Commands,  Next: Options,  Prev: Input,  Up: Top++3 Commands+**********++hledger provides various subcommands for getting things done.  Most of+these commands do not change the journal file; they just read it and+output a report.  A few commands assist with adding data and file+management.++   To show the commands list, run 'hledger' with no arguments.  The+commands are described in detail in PART 4: COMMANDS, below.++   To use a particular command, run 'hledger CMD [CMDOPTS] [CMDARGS]',++   * CMD is the full command name, or its standard abbreviation shown in+     the commands list, or any unambiguous prefix of the name.++   * CMDOPTS are command-specific options, if any.  Command-specific+     options must be written after the command name.  Eg: 'hledger print+     -x'.++   * CMDARGS are additional arguments to the command, if any.  Most+     hledger commands accept arguments representing a query, to limit+     the data in some way.  Eg: 'hledger reg assets:checking'.++   To list a command's options, arguments, and documentation in the+terminal, run 'hledger CMD -h'.  Eg: 'hledger bal -h'.++* Menu:++* Add-on commands::+++File: hledger.info,  Node: Add-on commands,  Up: Commands++3.1 Add-on commands+===================++In addition to the built-in commands, you can install _add-on commands_:+programs or scripts named "hledger-SOMETHING", which will also appear in+hledger's commands list.  If you used the hledger-install script, you+will have several add-ons installed already.  Some more can be found in+hledger's bin/ directory, documented at+https://hledger.org/scripts.html.++   More precisely, add-on commands are programs or scripts in your+shell's PATH, whose name starts with "hledger-" and ends with no+extension or a recognised extension (".bat", ".com", ".exe", ".hs",+".js", ".lhs", ".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"),+and (on unix and mac) which has executable permission for the current+user.++   You can run add-on commands using hledger, much like built-in+commands: 'hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]'.  But note+the double hyphen argument, required before add-on-specific options.+Eg: 'hledger ui -- --watch' or 'hledger web -- --serve'.  If this causes+difficulty, you can always run the add-on directly, without using+'hledger': 'hledger-ui --watch' or 'hledger-web --serve'.+++File: hledger.info,  Node: Options,  Next: Command line tips,  Prev: Commands,  Up: Top++4 Options+*********++Run 'hledger -h' to see general command line help, and general options+which are common to most hledger commands.  These options can be written+anywhere on the command line.  They can be grouped into help, input, and+reporting options:++* Menu:++* General help options::+* General input options::+* General reporting options::+++File: hledger.info,  Node: General help options,  Next: General input options,  Up: Options++4.1 General help options+========================++'-h --help'++     show general or COMMAND help+'--man'++     show general or COMMAND user manual with man+'--info'++     show general or COMMAND user manual with info+'--version'++     show general or ADDONCMD version+'--debug[=N]'++     show debug output (levels 1-9, default: 1)+++File: hledger.info,  Node: General input options,  Next: General reporting options,  Prev: General help options,  Up: Options++4.2 General input options+=========================++'-f FILE --file=FILE'++     use a different input file.  For stdin, use - (default:+     '$LEDGER_FILE' or '$HOME/.hledger.journal')+'--rules-file=RULESFILE'++     Conversion rules file to use when reading CSV (default: FILE.rules)+'--separator=CHAR'++     Field separator to expect when reading CSV (default: ',')+'--alias=OLD=NEW'++     rename accounts named OLD to NEW+'--anon'++     anonymize accounts and payees+'--pivot FIELDNAME'++     use some other field or tag for the account name+'-I --ignore-assertions'++     disable balance assertion checks (note: does not disable balance+     assignments)+'-s --strict'++     do extra error checking (check that all posted accounts are+     declared)+++File: hledger.info,  Node: General reporting options,  Prev: General input options,  Up: Options++4.3 General reporting options+=============================++'-b --begin=DATE'++     include postings/txns on or after this date (will be adjusted to+     preceding subperiod start when using a report interval)+'-e --end=DATE'++     include postings/txns before this date (will be adjusted to+     following subperiod end when using a report interval)+'-D --daily'++     multiperiod/multicolumn report by day+'-W --weekly'++     multiperiod/multicolumn report by week+'-M --monthly'++     multiperiod/multicolumn report by month+'-Q --quarterly'++     multiperiod/multicolumn report by quarter+'-Y --yearly'++     multiperiod/multicolumn report by year+'-p --period=PERIODEXP'++     set start date, end date, and/or reporting interval all at once+     using period expressions syntax+'--date2'++     match the secondary date instead (see command help for other+     effects)+'--today=DATE'++     override today's date (affects relative smart dates, for+     tests/examples)+'-U --unmarked'++     include only unmarked postings/txns (can combine with -P or -C)+'-P --pending'++     include only pending postings/txns+'-C --cleared'++     include only cleared postings/txns+'-R --real'++     include only non-virtual postings+'-NUM --depth=NUM'++     hide/aggregate accounts or postings more than NUM levels deep+'-E --empty'++     show items with zero amount, normally hidden (and vice-versa in+     hledger-ui/hledger-web)+'-B --cost'++     convert amounts to their cost/selling amount at transaction time+'-V --market'++     convert amounts to their market value in default valuation+     commodities+'-X --exchange=COMM'++     convert amounts to their market value in commodity COMM+'--value'++     convert amounts to cost or market value, more flexibly than+     -B/-V/-X+'--infer-equity'++     infer conversion equity postings from costs+'--infer-costs'++     infer costs from conversion equity postings+'--infer-market-prices'++     use costs as additional market prices, as if they were P directives+'--forecast'++     generate transactions from periodic rules, between the latest+     recorded txn and 6 months from today, or during the specified+     PERIOD (= is required).  Auto posting rules will be applied to+     these transactions as well.  Also, in hledger-ui make future-dated+     transactions visible.+'--auto'++     generate extra postings by applying auto posting rules to all txns+     (not just forecast txns)+'--verbose-tags'++     add visible tags indicating transactions or postings which have+     been generated/modified+'--commodity-style'++     Override the commodity style in the output for the specified+     commodity.  For example 'EUR1.000,00'.+'--color=WHEN (or --colour=WHEN)'++     Should color-supporting commands use ANSI color codes in text+     output.  'auto' (default): whenever stdout seems to be a+     color-supporting terminal.  'always' or 'yes': always, useful eg+     when piping output into 'less -R'. 'never' or 'no': never.  A+     NO_COLOR environment variable overrides this.+'--pretty[=WHEN]'++     Show prettier output, e.g.  using unicode box-drawing characters.+     Accepts 'yes' (the default) or 'no' ('y', 'n', 'always', 'never'+     also work).  If you provide an argument you must use '=', e.g.+     '-pretty=yes'.++   When a reporting option appears more than once in the command line,+the last one takes precedence.++   Some reporting options can also be written as query arguments.+++File: hledger.info,  Node: Command line tips,  Next: Output,  Prev: Options,  Up: Top++5 Command line tips+*******************++Here are some details useful to know about for hledger command lines+(and elsewhere).  Feel free to skip this section until you need it.++* Menu:++* Option repetition::+* Special characters::+* Unicode characters::+* Regular expressions::+* Argument files::+++File: hledger.info,  Node: Option repetition,  Next: Special characters,  Up: Command line tips++5.1 Option repetition+=====================++If options are repeated in a command line, hledger will generally use+the last (right-most) occurence.+++File: hledger.info,  Node: Special characters,  Next: Unicode characters,  Prev: Option repetition,  Up: Command line tips++5.2 Special characters+======================++* Menu:++* Single escaping shell metacharacters::+* Double escaping regular expression metacharacters::+* Triple escaping for add-on commands::+* Less escaping::+++File: hledger.info,  Node: Single escaping shell metacharacters,  Next: Double escaping regular expression metacharacters,  Up: Special characters++5.2.1 Single escaping (shell metacharacters)+--------------------------------------------++In shell command lines, characters significant to your shell - such as+spaces, '<', '>', '(', ')', '|', '$' and '\' - should be "shell-escaped"+if you want hledger to see them.  This is done by enclosing them in+single or double quotes, or by writing a backslash before them.  Eg to+match an account name containing a space:++$ hledger register 'credit card'++   or:++$ hledger register credit\ card++   Windows users should keep in mind that 'cmd' treats single quote as a+regular character, so you should be using double quotes exclusively.+PowerShell treats both single and double quotes as quotes.+++File: hledger.info,  Node: Double escaping regular expression metacharacters,  Next: Triple escaping for add-on commands,  Prev: Single escaping shell metacharacters,  Up: Special characters++5.2.2 Double escaping (regular expression metacharacters)+---------------------------------------------------------++Characters significant in regular expressions (described below) - such+as '.', '^', '$', '[', ']', '(', ')', '|', and '\' - may need to be+"regex-escaped" if you don't want them to be interpreted by hledger's+regular expression engine.  This is done by writing backslashes before+them, but since backslash is typically also a shell metacharacter, both+shell-escaping and regex-escaping will be needed.  Eg to match a literal+'$' sign while using the bash shell:++$ hledger balance cur:'\$'++   or:++$ hledger balance cur:\\$+++File: hledger.info,  Node: Triple escaping for add-on commands,  Next: Less escaping,  Prev: Double escaping regular expression metacharacters,  Up: Special characters++5.2.3 Triple escaping (for add-on commands)+-------------------------------------------++When you use hledger to run an external add-on command (described+below), one level of shell-escaping is lost from any options or+arguments intended for by the add-on command, so those need an extra+level of shell-escaping.  Eg to match a literal '$' sign while using the+bash shell and running an add-on command ('ui'):++$ hledger ui cur:'\\$'++   or:++$ hledger ui cur:\\\\$++   If you wondered why _four_ backslashes, perhaps this helps:++unescaped:        '$'+escaped:          '\$'+double-escaped:   '\\$'+triple-escaped:   '\\\\$'++   Or, you can avoid the extra escaping by running the add-on executable+directly:++$ hledger-ui cur:\\$+++File: hledger.info,  Node: Less escaping,  Prev: Triple escaping for add-on commands,  Up: Special characters++5.2.4 Less escaping+-------------------++Options and arguments are sometimes used in places other than the shell+command line, where shell-escaping is not needed, so there you should+use one less level of escaping.  Those places include:++   * an @argumentfile+   * hledger-ui's filter field+   * hledger-web's search form+   * GHCI's prompt (used by developers).+++File: hledger.info,  Node: Unicode characters,  Next: Regular expressions,  Prev: Special characters,  Up: Command line tips++5.3 Unicode characters+======================++hledger is expected to handle non-ascii characters correctly:++   * they should be parsed correctly in input files and on the command+     line, by all hledger tools (add, iadd, hledger-web's+     search/add/edit forms, etc.)++   * they should be displayed correctly by all hledger tools, and+     on-screen alignment should be preserved.++   This requires a well-configured environment.  Here are some tips:++   * A system locale must be configured, and it must be one that can+     decode the characters being used.  In bash, you can set a locale+     like this: 'export LANG=en_US.UTF-8'.  There are some more details+     in Troubleshooting.  This step is essential - without it, hledger+     will quit on encountering a non-ascii character (as with all+     GHC-compiled programs).++   * your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..)+     must support unicode++   * the terminal must be using a font which includes the required+     unicode glyphs++   * the terminal should be configured to display wide characters as+     double width (for report alignment)++   * on Windows, for best results you should run hledger in the same+     kind of environment in which it was built.  Eg hledger built in the+     standard CMD.EXE environment (like the binaries on our download+     page) might show display problems when run in a cygwin or msys+     terminal, and vice versa.  (See eg #961).+++File: hledger.info,  Node: Regular expressions,  Next: Argument files,  Prev: Unicode characters,  Up: Command line tips++5.4 Regular expressions+=======================++A regular expression (regexp) is a small piece of text where certain+characters (like '.', '^', '$', '+', '*', '()', '|', '[]', '\') have+special meanings, forming a tiny language for matching text precisely -+very useful in hledger and elsewhere.  To learn all about them, visit+regular-expressions.info.++   hledger supports regexps whenever you are entering a pattern to match+something, eg in query arguments, account aliases, CSV if rules,+hledger-web's search form, hledger-ui's '/' search, etc.  You may need+to wrap them in quotes, especially at the command line (see Special+characters above).  Here are some examples:++   Account name queries (quoted for command line use):++Regular expression:  Matches:+-------------------  ------------------------------------------------------------+bank                 assets:bank, assets:bank:savings, expenses:art:banksy, ...+:bank                assets:bank:savings, expenses:art:banksy+:bank:               assets:bank:savings+'^bank'              none of those ( ^ matches beginning of text )+'bank$'              assets:bank   ( $ matches end of text )+'big \$ bank'        big $ bank    ( \ disables following character's special meaning )+'\bbank\b'           assets:bank, assets:bank:savings  ( \b matches word boundaries )+'(sav|check)ing'     saving or checking  ( (|) matches either alternative )+'saving|checking'    saving or checking  ( outer parentheses are not needed )+'savings?'           saving or savings   ( ? matches 0 or 1 of the preceding thing )+'my +bank'           my bank, my  bank, ... ( + matches 1 or more of the preceding thing )+'my *bank'           mybank, my bank, my  bank, ... ( * matches 0 or more of the preceding thing )+'b.nk'               bank, bonk, b nk, ... ( . matches any character )++   Some other queries:++desc:'amazon|amzn|audible'  Amazon transactions+cur:EUR              amounts with commodity symbol containing EUR+cur:'\$'             amounts with commodity symbol containing $+cur:'^\$$'           only $ amounts, not eg AU$ or CA$+cur:....?            amounts with 4-or-more-character symbols+tag:.=202[1-3]       things with any tag whose value contains 2021, 2022 or 2023++   Account name aliases: accept '.' instead of ':' as account separator:++alias /\./=:         replaces all periods in account names with colons++   Show multiple top-level accounts combined as one:++--alias='/^[^:]+/=combined'  ( [^:] matches any character other than : )++   Show accounts with the second-level part removed:++--alias '/^([^:]+):[^:]+/ = \1'+                     match a top-level account and a second-level account+                     and replace those with just the top-level account+                     ( \1 in the replacement text means "whatever was matched+                     by the first parenthesised part of the regexp"++   CSV rules: match CSV records containing dining-related MCC codes:++if \?MCC581[124]++   Match CSV records with a specific amount around the end/start of+month:++if %amount \b3\.99+&  %date   (29|30|31|01|02|03)$++* Menu:++* hledger's regular expressions::+++File: hledger.info,  Node: hledger's regular expressions,  Up: Regular expressions++5.4.1 hledger's regular expressions+-----------------------------------++hledger's regular expressions come from the regex-tdfa library.  If+they're not doing what you expect, it's important to know exactly what+they support:++  1. they are case insensitive+  2. they are infix matching (they do not need to match the entire thing+     being matched)+  3. they are POSIX ERE (extended regular expressions)+  4. they also support GNU word boundaries ('\b', '\B', '\<', '\>')+  5. backreferences are supported when doing text replacement in account+     aliases or CSV rules, where backreferences can be used in the+     replacement string to reference capturing groups in the search+     regexp.  Otherwise, if you write '\1', it will match the digit '1'.+  6. they do not support mode modifiers ('(?s)'), character classes+     ('\w', '\d'), or anything else not mentioned above.++   Some things to note:++   * In the 'alias' directive and '--alias' option, regular expressions+     must be enclosed in forward slashes ('/REGEX/').  Elsewhere in+     hledger, these are not required.++   * In queries, to match a regular expression metacharacter like '$' as+     a literal character, prepend a backslash.  Eg to search for amounts+     with the dollar sign in hledger-web, write 'cur:\$'.++   * On the command line, some metacharacters like '$' have a special+     meaning to the shell and so must be escaped at least once more.+     See Special characters.+++File: hledger.info,  Node: Argument files,  Prev: Regular expressions,  Up: Command line tips++5.5 Argument files+==================++You can save a set of command line options and arguments in a file, and+then reuse them by writing '@FILENAME' as a command line argument.  Eg:+'hledger bal @foo.args'.++   Inside the argument file, each line should contain just one option or+argument.  Don't use spaces except inside quotes (or you'll see a+confusing error); write '=' (or nothing) between a flag and its+argument.  For the special characters mentioned above, use one less+level of quoting than you would at the command prompt.+++File: hledger.info,  Node: Output,  Next: Environment,  Prev: Command line tips,  Up: Top++6 Output+********++* Menu:++* Output destination::+* Output format::+* Commodity styles::+* Colour::+* Box-drawing::+* Paging::+* Debug output::+++File: hledger.info,  Node: Output destination,  Next: Output format,  Up: Output++6.1 Output destination+======================++hledger commands send their output to the terminal by default.  You can+of course redirect this, eg into a file, using standard shell syntax:++$ hledger print > foo.txt++   Some commands (print, register, stats, the balance commands) also+provide the '-o/--output-file' option, which does the same thing without+needing the shell.  Eg:++$ hledger print -o foo.txt+$ hledger print -o -        # write to stdout (the default)+++File: hledger.info,  Node: Output format,  Next: Commodity styles,  Prev: Output destination,  Up: Output++6.2 Output format+=================++Some commands offer other kinds of output, not just text on the+terminal.  Here are those commands and the formats currently supported:++-                 txt             csv/tsv         html              json  sql+-------------------------------------------------------------------------------+aregister         Y               Y               Y                 Y+balance           Y _1_           Y _1_           Y _1,2_           Y+balancesheet      Y _1_           Y _1_           Y _1_             Y+balancesheetequityY _1_           Y _1_           Y _1_             Y+cashflow          Y _1_           Y _1_           Y _1_             Y+incomestatement   Y _1_           Y _1_           Y _1_             Y+print             Y               Y                                 Y     Y+register          Y               Y                                 Y++   * _1 Also affected by the balance commands' '--layout' option._+   * _2 'balance' does not support html output without a report interval+     or with '--budget'._++   The output format is selected by the '-O/--output-format=FMT' option:++$ hledger print -O csv    # print CSV on stdout++   or by the filename extension of an output file specified with the+'-o/--output-file=FILE.FMT' option:++$ hledger balancesheet -o foo.csv    # write CSV to foo.csv++   The '-O' option can be combined with '-o' to override the file+extension, if needed:++$ hledger balancesheet -o foo.txt -O csv    # write CSV to foo.txt++   Some notes about the various output formats:++* Menu:++* CSV output::+* HTML output::+* JSON output::+* SQL output::+++File: hledger.info,  Node: CSV output,  Next: HTML output,  Up: Output format++6.2.1 CSV output+----------------++   * In CSV output, digit group marks (such as thousands separators) are+     disabled automatically.+++File: hledger.info,  Node: HTML output,  Next: JSON output,  Prev: CSV output,  Up: Output format++6.2.2 HTML output+-----------------++   * HTML output can be styled by an optional 'hledger.css' file in the+     same directory.+++File: hledger.info,  Node: JSON output,  Next: SQL output,  Prev: HTML output,  Up: Output format++6.2.3 JSON output+-----------------++   * This is not yet much used; real-world feedback is welcome.++   * Our JSON is rather large and verbose, since it is a faithful+     representation of hledger's internal data types.  To understand the+     JSON, read the Haskell type definitions, which are mostly in+     https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs.++   * hledger represents quantities as Decimal values storing up to 255+     significant digits, eg for repeating decimals.  Such numbers can+     arise in practice (from automatically-calculated transaction+     prices), and would break most JSON consumers.  So in JSON, we show+     quantities as simple Numbers with at most 10 decimal places.  We+     don't limit the number of integer digits, but that part is under+     your control.  We hope this approach will not cause problems in+     practice; if you find otherwise, please let us know.  (Cf #1195)+++File: hledger.info,  Node: SQL output,  Prev: JSON output,  Up: Output format++6.2.4 SQL output+----------------++   * This is not yet much used; real-world feedback is welcome.++   * SQL output is expected to work at least with SQLite, MySQL and+     Postgres.++   * For SQLite, it will be more useful if you modify the generated 'id'+     field to be a PRIMARY KEY. Eg:++     $ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ...++   * SQL output is structured with the expectations that statements will+     be executed in the empty database.  If you already have tables+     created via SQL output of hledger, you would probably want to+     either clear tables of existing data (via 'delete' or 'truncate'+     SQL statements) or drop tables completely as otherwise your+     postings will be duped.+++File: hledger.info,  Node: Commodity styles,  Next: Colour,  Prev: Output format,  Up: Output++6.3 Commodity styles+====================++When displaying amounts, hledger infers a standard display style for+each commodity/currency, as described below in Commodity display style.++   If needed, this can be overridden by a '-c/--commodity-style' option+(except for cost amounts and amounts displayed by the 'print' command,+which are always displayed with all decimal digits).  For example, the+following will force dollar amounts to be displayed as shown:++$ hledger print -c '$1.000,0'++   This option can repeated to set the display style for multiple+commodities/currencies.  Its argument is as described in the commodity+directive.+++File: hledger.info,  Node: Colour,  Next: Box-drawing,  Prev: Commodity styles,  Up: Output++6.4 Colour+==========++In terminal output, some commands can produce colour when the terminal+supports it:++   * if the '--color/--colour' option is given a value of 'yes' or+     'always' (or 'no' or 'never'), colour will (or will not) be used;+   * otherwise, if the 'NO_COLOR' environment variable is set, colour+     will not be used;+   * otherwise, colour will be used if the output (terminal or file)+     supports it.+++File: hledger.info,  Node: Box-drawing,  Next: Paging,  Prev: Colour,  Up: Output++6.5 Box-drawing+===============++In terminal output, you can enable unicode box-drawing characters to+render prettier tables:++   * if the '--pretty' option is given a value of 'yes' or 'always' (or+     'no' or 'never'), unicode characters will (or will not) be used;+   * otherwise, unicode characters will not be used.+++File: hledger.info,  Node: Paging,  Next: Debug output,  Prev: Box-drawing,  Up: Output++6.6 Paging+==========++When showing long output in the terminal, hledger will try to use the+pager specified by the 'PAGER' environment variable, or 'less', or+'more'.  (A pager is a helper program that shows one page at a time+rather than scrolling everything off screen).  Currently it does this+only for help output, not for reports; specifically,++   * when listing commands, with 'hledger'+   * when showing help with 'hledger [CMD] --help',+   * when viewing manuals with 'hledger help' or 'hledger --man'.++   Note the pager is expected to handle ANSI codes, which hledger uses+eg for bold emphasis.  For the common pager 'less' (and its 'more'+compatibility mode), we add 'R' to the 'LESS' and 'MORE' environment+variables to make this work.  If you use a different pager, you might+need to configure it similarly, to avoid seeing junk on screen (let us+know).  Otherwise, you can set the 'NO_COLOR' environment variable to 1+to disable all ANSI output (see Colour).+++File: hledger.info,  Node: Debug output,  Prev: Paging,  Up: Output++6.7 Debug output+================++We intend hledger to be relatively easy to troubleshoot, introspect and+develop.  You can add '--debug[=N]' to any hledger command line to see+additional debug output.  N ranges from 1 (least output, the default) to+9 (maximum output).  Typically you would start with 1 and increase until+you are seeing enough.  Debug output goes to stderr, and is not affected+by '-o/--output-file' (unless you redirect stderr to stdout, eg:+'2>&1').  It will be interleaved with normal output, which can help+reveal when parts of the code are evaluated.  To capture debug output in+a log file instead, you can usually redirect stderr, eg:++hledger bal --debug=3 2>hledger.log+++File: hledger.info,  Node: Environment,  Next: PART 2 DATA FORMATS,  Prev: Output,  Up: Top++7 Environment+*************++These environment variables affect hledger:++   *COLUMNS* This is normally set by your terminal; some hledger+commands ('register') will format their output to this width.  If not+set, they will try to use the available terminal width.++   *LEDGER_FILE* The main journal file to use when not specified with+'-f/--file'.  Default: '$HOME/.hledger.journal'.++   *NO_COLOR* If this environment variable is set (with any value),+hledger will not use ANSI color codes in terminal output, unless+overridden by an explicit '--color/--colour' option.+++File: hledger.info,  Node: PART 2 DATA FORMATS,  Next: Journal,  Prev: Environment,  Up: Top++8 PART 2: DATA FORMATS+**********************+++File: hledger.info,  Node: Journal,  Next: CSV,  Prev: PART 2 DATA FORMATS,  Up: Top++9 Journal+*********++hledger's default file format, representing a General Journal.  Here's a+cheatsheet/mini-tutorial, or you can skip ahead to About journal format.++* Menu:++* Journal cheatsheet::+* About journal format::+* Comments::+* Transactions::+* Dates::+* Status::+* Code::+* Description::+* Transaction comments::+* Postings::+* Account names::+* Amounts::+* Costs::+* Balance assertions::+* Posting comments::+* Tags::+* Directives::+* account directive::+* alias directive::+* commodity directive::+* decimal-mark directive::+* include directive::+* P directive::+* payee directive::+* tag directive::+* Periodic transactions::+* Auto postings::+* Other syntax::+++File: hledger.info,  Node: Journal cheatsheet,  Next: About journal format,  Up: Journal++9.1 Journal cheatsheet+======================++# Here is the main syntax of hledger's journal format+# (omitting extra Ledger compatibility syntax).+# hledger journals contain comments, directives, and transactions, in any order:++###############################################################################+# 1. Comment lines are for notes or temporarily disabling things.+# They begin with #, ;, or a line containing the word "comment".++# hash comment line+; semicolon comment line+comment+These lines+are commented.+end comment++# Some but not all hledger entries can have same-line comments attached to them,+# from ; (semicolon) to end of line.++###############################################################################+# 2. Directives modify parsing or reports in some way.+# They begin with a word or letter (or symbol).++account actifs     ; type:A, declare an account that is an Asset. 2+ spaces before ;.+account passifs    ; type:L, declare an account that is a Liability, and so on.. (ALERX)+alias chkg = assets:checking+commodity $0.00+decimal-mark .+include /dev/null+payee Whole Foods+P 2022-01-01 AAAA $1.40+~ monthly    budget goals  ; <- 2+ spaces between period expression and description+    expenses:food       $400+    expenses:home      $1000+    budgeted++###############################################################################+# 3. Transactions are what it's all about; they are dated events,+# usually describing movements of money.+# They begin with a date.++# DATE DESCRIPTION           ; This is a transaction comment.+#   ACCOUNT NAME 1  AMOUNT1  ; <- posting 1. This is a posting comment.+#   ACCOUNT NAME 2  AMOUNT2  ; <- posting 2. Postings must be indented.+#               ; ^^ At least 2 spaces between account and amount.+#   ...  ; Any number of postings is allowed. The amounts must balance (sum to 0).++2022-01-01 opening balances are declared this way+    assets:checking          $1000  ; Account names can be anything. lower case is easy to type.+    assets:savings           $1000  ; assets, liabilities, equity, revenues, expenses are common.+    assets:cash:wallet        $100  ; : indicates subaccounts.+    liabilities:credit card  $-200  ; liabilities, equity, revenues balances are usually negative.+    equity                          ; One amount can be left blank; $-1900 is inferred here.++2022-04-15 * (#12345) pay taxes+    ; There can be a ! or * after the date meaning "pending" or "cleared".+    ; There can be a transaction code (text in parentheses) after the date/status.+    ; Amounts' sign represents direction of flow, or credit/debit:+    assets:checking          $-500  ; minus means removed from this account (credit)+    expenses:tax:us:2021      $500  ; plus  means added to this account (debit)+                                    ; revenue/expense categories are also "accounts"++2022-01-01                          ; The description is optional.+    ; Any currency/commodity symbols are allowed, on either side.+    assets:cash:wallet     GBP -10+    expenses:clothing       GBP 10+    assets:gringotts           -10 gold+    assets:pouch                10 gold+    revenues:gifts              -2 "Liquorice Wands"  ; Complex symbols+    assets:bag                   2 "Liquorice Wands"  ; must be double-quoted.++2022-01-01 Cost in another commodity can be noted with @ or @@+    assets:investments           2.0 AAAA @ $1.50  ; @  means per-unit cost+    assets:investments           3.0 AAAA @@ $4    ; @@ means total cost+    assets:checking            $-7.00++2022-01-02 assert balances+    ; Balances can be asserted for extra error checking, in any transaction.+    assets:investments           0 AAAA = 5.0 AAAA+    assets:pouch                 0 gold = 10 gold+    assets:savings              $0      = $1000++1999-12-31 Ordering transactions by date is recommended but not required.+    ; Postings are not required.++2022.01.01 These date+2022/1/1   formats are+12/31      also allowed (but consistent YYYY-MM-DD is recommended).+++File: hledger.info,  Node: About journal format,  Next: Comments,  Prev: Journal cheatsheet,  Up: Journal++9.2 About journal format+========================++hledger's usual data source is a plain text file containing journal+entries in hledger journal format.  This file represents a standard+accounting general journal.  I use file names ending in '.journal', but+that's not required.  The journal file contains a number of transaction+entries, each describing a transfer of money (or any commodity) between+two or more named accounts, in a simple format readable by both hledger+and humans.++   hledger's journal format is compatible with most of Ledger's journal+format, but not all of it.  The differences and interoperation tips are+described at hledger and Ledger.  With some care, and by avoiding+incompatible features, you can keep your hledger journal readable by+Ledger and vice versa.  This can useful eg for comparing the behaviour+of one app against the other.++   You can use hledger without learning any more about this file; just+use the add or web or import commands to create and update it.++   Many users, though, edit the journal file with a text editor, and+track changes with a version control system such as git.  Editor addons+such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and+hledger-vscode for Visual Studio Code, make this easier, adding colour,+formatting, tab completion, and useful commands.  See Editor+configuration at hledger.org for the full list.++   Here's a description of each part of the file format (and hledger's+data model).++   A hledger journal file can contain three kinds of thing: file+comments, transactions, and/or directives (counting periodic transaction+rules and auto posting rules as directives).+++File: hledger.info,  Node: Comments,  Next: Transactions,  Prev: About journal format,  Up: Journal++9.3 Comments+============++Lines in the journal will be ignored if they begin with a hash ('#') or+a semicolon (';').  (See also Other syntax.)  hledger will also ignore+regions beginning with a 'comment' line and ending with an 'end comment'+line (or file end).  Here's a suggestion for choosing between them:++   * '#' for top-level notes+   * ';' for commenting out things temporarily+   * 'comment' for quickly commenting large regions (remember it's+     there, or you might get confused)++   Eg:++# a comment line+; another commentline+comment+A multi-line comment block,+continuing until "end comment" directive+or the end of the current file.+end comment++   Some hledger entries can have same-line comments attached to them,+from ; (semicolon) to end of line.  See Transaction comments, Posting+comments, and Account comments below.+++File: hledger.info,  Node: Transactions,  Next: Dates,  Prev: Comments,  Up: Journal++9.4 Transactions+================++Transactions are the main unit of information in a journal file.  They+represent events, typically a movement of some quantity of commodities+between two or more named accounts.++   Each transaction is recorded as a journal entry, beginning with a+simple date in column 0.  This can be followed by any of the following+optional fields, separated by spaces:++   * a status character (empty, '!', or '*')+   * a code (any short number or text, enclosed in parentheses)+   * a description (any remaining text until end of line or a semicolon)+   * a comment (any remaining text following a semicolon until end of+     line, and any following indented lines beginning with a semicolon)+   * 0 or more indented _posting_ lines, describing what was transferred+     and the accounts involved (indented comment lines are also allowed,+     but not blank lines or non-indented lines).++   Here's a simple journal file containing one transaction:++2008/01/01 income+  assets:bank:checking   $1+  income:salary         $-1+++File: hledger.info,  Node: Dates,  Next: Status,  Prev: Transactions,  Up: Journal++9.5 Dates+=========++* Menu:++* Simple dates::+* Posting dates::+++File: hledger.info,  Node: Simple dates,  Next: Posting dates,  Up: Dates++9.5.1 Simple dates+------------------++Dates in the journal file use _simple dates_ format: 'YYYY-MM-DD' or+'YYYY/MM/DD' or 'YYYY.MM.DD', with leading zeros optional.  The year may+be omitted, in which case it will be inferred from the context: the+current transaction, the default year set with a 'Y' directive, or the+current date when the command is run.  Some examples: '2010-01-31',+'2010/01/31', '2010.1.31', '1/31'.++   (The UI also accepts simple dates, as well as the more flexible smart+dates documented in the hledger manual.)+++File: hledger.info,  Node: Posting dates,  Prev: Simple dates,  Up: Dates++9.5.2 Posting dates+-------------------++You can give individual postings a different date from their parent+transaction, by adding a posting comment containing a tag (see below)+like 'date:DATE'.  This is probably the best way to control posting+dates precisely.  Eg in this example the expense should appear in May+reports, and the deduction from checking should be reported on 6/1 for+easy bank reconciliation:++2015/5/30+    expenses:food     $10  ; food purchased on saturday 5/30+    assets:checking        ; bank cleared it on monday, date:6/1++$ hledger -f t.j register food+2015-05-30                      expenses:food                  $10           $10++$ hledger -f t.j register checking+2015-06-01                      assets:checking               $-10          $-10++   DATE should be a simple date; if the year is not specified it will+use the year of the transaction's date.+The 'date:' tag must have a valid simple date value if it is present, eg+a 'date:' tag with no value is not allowed.+++File: hledger.info,  Node: Status,  Next: Code,  Prev: Dates,  Up: Journal++9.6 Status+==========++Transactions, or individual postings within a transaction, can have a+status mark, which is a single character before the transaction+description or posting account name, separated from it by a space,+indicating one of three statuses:++mark  status+ +-----------------+      unmarked+'!'   pending+'*'   cleared++   When reporting, you can filter by status with the '-U/--unmarked',+'-P/--pending', and '-C/--cleared' flags; or the 'status:', 'status:!',+and 'status:*' queries; or the U, P, C keys in hledger-ui.++   Note, in Ledger and in older versions of hledger, the "unmarked"+state is called "uncleared".  As of hledger 1.3 we have renamed it to+unmarked for clarity.++   To replicate Ledger and old hledger's behaviour of also matching+pending, combine -U and -P.++   Status marks are optional, but can be helpful eg for reconciling with+real-world accounts.  Some editor modes provide highlighting and+shortcuts for working with status.  Eg in Emacs ledger-mode, you can+toggle transaction status with C-c C-e, or posting status with C-c C-c.++   What "uncleared", "pending", and "cleared" actually mean is up to+you.  Here's one suggestion:++status     meaning+--------------------------------------------------------------------------+uncleared  recorded but not yet reconciled; needs review+pending    tentatively reconciled (if needed, eg during a big+           reconciliation)+cleared    complete, reconciled as far as possible, and considered+           correct++   With this scheme, you would use '-PC' to see the current balance at+your bank, '-U' to see things which will probably hit your bank soon+(like uncashed checks), and no flags to see the most up-to-date state of+your finances.+++File: hledger.info,  Node: Code,  Next: Description,  Prev: Status,  Up: Journal++9.7 Code+========++After the status mark, but before the description, you can optionally+write a transaction "code", enclosed in parentheses.  This is a good+place to record a check number, or some other important transaction id+or reference number.+++File: hledger.info,  Node: Description,  Next: Transaction comments,  Prev: Code,  Up: Journal++9.8 Description+===============++A transaction's description is the rest of the line following the date+and status mark (or until a comment begins).  Sometimes called the+"narration" in traditional bookkeeping, it can be used for whatever you+wish, or left blank.  Transaction descriptions can be queried, unlike+comments.++* Menu:++* Payee and note::+++File: hledger.info,  Node: Payee and note,  Up: Description++9.8.1 Payee and note+--------------------++You can optionally include a '|' (pipe) character in descriptions to+subdivide the description into separate fields for payee/payer name on+the left (up to the first '|') and an additional note field on the right+(after the first '|').  This may be worthwhile if you need to do more+precise querying and pivoting by payee or by note.+++File: hledger.info,  Node: Transaction comments,  Next: Postings,  Prev: Description,  Up: Journal++9.9 Transaction comments+========================++Text following ';', after a transaction description, and/or on indented+lines immediately below it, form comments for that transaction.  They+are reproduced by 'print' but otherwise ignored, except they may contain+tags, which are not ignored.++2012-01-01 something  ; a transaction comment+    ; a second line of transaction comment+    expenses   1+    assets+++File: hledger.info,  Node: Postings,  Next: Account names,  Prev: Transaction comments,  Up: Journal++9.10 Postings+=============++A posting is an addition of some amount to, or removal of some amount+from, an account.  Each posting line begins with at least one space or+tab (2 or 4 spaces is common), followed by:++   * (optional) a status character (empty, '!', or '*'), followed by a+     space+   * (required) an account name (any text, optionally containing *single+     spaces*, until end of line or a double space)+   * (optional) *two or more spaces* or tabs followed by an amount.++   Positive amounts are being added to the account, negative amounts are+being removed.++   The amounts within a transaction must always sum up to zero.  As a+convenience, one amount may be left blank; it will be inferred so as to+balance the transaction.++   Be sure to note the unusual two-space delimiter between account name+and amount.  This makes it easy to write account names containing+spaces.  But if you accidentally leave only one space (or tab) before+the amount, the amount will be considered part of the account name.+++File: hledger.info,  Node: Account names,  Next: Amounts,  Prev: Postings,  Up: Journal++9.11 Account names+==================++Accounts are the main way of categorising things in hledger.  As in+Double Entry Bookkeeping, they can represent real world accounts (such+as a bank account), or more abstract categories such as "money borrowed+from Frank" or "money spent on electricity".++   You can use any account names you like, but we usually start with the+traditional accounting categories, which in english are 'assets',+'liabilities', 'equity', 'revenues', 'expenses'.  (You might see these+referred to as A, L, E, R, X for short.)++   For more precise reporting, we usually divide the top level accounts+into more detailed subaccounts, by writing a full colon between account+name parts.  For example, from the account names 'assets:bank:checking'+and 'expenses:food', hledger will infer this hierarchy of five accounts:++assets+assets:bank+assets:bank:checking+expenses+expenses:food++   Shown as an outline, the hierarchical tree structure is more clear:++assets+ bank+  checking+expenses+ food++   hledger reports can summarise the account tree to any depth, so you+can go as deep as you like with subcategories, but keeping your account+names relatively simple may be best when starting out.++   Account names may be capitalised or not; they may contain letters,+numbers, symbols, or single spaces.  Note, when an account name and an+amount are written on the same line, they must be separated by *two or+more spaces* (or tabs).++   Parentheses or brackets enclosing the full account name indicate+virtual postings, described below.  Parentheses or brackets internal to+the account name have no special meaning.++   Account names can be altered temporarily or permanently by account+aliases.+++File: hledger.info,  Node: Amounts,  Next: Costs,  Prev: Account names,  Up: Journal++9.12 Amounts+============++After the account name, there is usually an amount.  (Important: between+account name and amount, there must be *two or more spaces*.)++   hledger's amount format is flexible, supporting several international+formats.  Here are some examples.  Amounts have a number (the+"quantity"):++1++   ..and usually a currency symbol or commodity name (more on this+below), to the left or right of the quantity, with or without a+separating space:++$1+4000 AAPL+3 "green apples"++   Amounts can be preceded by a minus sign (or a plus sign, though plus+is the default), The sign can be written before or after a left-side+commodity symbol:++-$1+$-1++   One or more spaces between the sign and the number are acceptable+when parsing (but they won't be displayed in output):+++ $1+$-      1++   Scientific E notation is allowed:++1E-6+EUR 1E3++* Menu:++* Decimal marks digit group marks::+* Commodity::+* Directives influencing number parsing and display::+* Commodity display style::+* Rounding::+++File: hledger.info,  Node: Decimal marks digit group marks,  Next: Commodity,  Up: Amounts++9.12.1 Decimal marks, digit group marks+---------------------------------------++A _decimal mark_ can be written as a period or a comma:++1.23+1,23++   In the integer part of the quantity (left of the decimal mark),+groups of digits can optionally be separated by a _digit group mark_ - a+space, comma, or period (different from the decimal mark):++     $1,000,000.00+  EUR 2.000.000,00+INR 9,99,99,999.00+      1 000 000.9455++   hledger is not biased towards period or comma decimal marks, so a+number containing just one period or comma, like '1,000' or '1.000', is+ambiguous.  In such cases hledger assumes it is a decimal mark, parsing+both of these as 1.++   To disambiguate these and ensure accurate number parsing, especially+if you use digit group marks, we recommend declaring the decimal mark.+You can declare it for each file with 'decimal-mark' directives, or for+each commodity with 'commodity' directives (described below).+++File: hledger.info,  Node: Commodity,  Next: Directives influencing number parsing and display,  Prev: Decimal marks digit group marks,  Up: Amounts++9.12.2 Commodity+----------------++Amounts in hledger have both a "quantity", which is a signed decimal+number, and a "commodity", which is a currency symbol, stock ticker, or+any word or phrase describing something you are tracking.++   If the commodity name contains non-letters (spaces, numbers, or+punctuation), you must always write it inside double quotes ('"green+apples"', '"ABC123"').++   If you write just a bare number, that too will have a commodity, with+name '""'; we call that the "no-symbol commodity".++   Actually, hledger combines these single-commodity amounts into more+powerful multi-commodity amounts, which are what it works with most of+the time.  A multi-commodity amount could be, eg: '1 USD, 2 EUR, 3.456+TSLA'.  In practice, you will only see multi-commodity amounts in+hledger's output; you can't write them directly in the journal file.++   (If you are writing scripts or working with hledger's internals,+these are the 'Amount' and 'MixedAmount' types.)+++File: hledger.info,  Node: Directives influencing number parsing and display,  Next: Commodity display style,  Prev: Commodity,  Up: Amounts++9.12.3 Directives influencing number parsing and display+--------------------------------------------------------++You can add 'decimal-mark' and 'commodity' directives to the journal, to+declare and control these things more explicitly and precisely.  These+are described below, but here's a quick example:++# the decimal mark character used by all amounts in this file (all commodities)+decimal-mark .++# display styles for the $, EUR, INR and no-symbol commodities:+commodity $1,000.00+commodity EUR 1.000,00+commodity INR 9,99,99,999.00+commodity 1 000 000.9455+++File: hledger.info,  Node: Commodity display style,  Next: Rounding,  Prev: Directives influencing number parsing and display,  Up: Amounts++9.12.4 Commodity display style+------------------------------++For the amounts in each commodity, hledger chooses a consistent display+style (symbol placement, decimal mark and digit group marks, number of+decimal digits) to use in most reports.  This is inferred as follows:++   First, if there's a 'D' directive declaring a default commodity, that+commodity symbol and amount format is applied to all no-symbol amounts+in the journal.++   Then each commodity's display style is determined from its+'commodity' directive.  We recommend always declaring commodities with+'commodity' directives, since they help ensure consistent display styles+and precisions, and bring other benefits such as error checking for+commodity symbols.++   But if a 'commodity' directive is not present, hledger infers a+commodity's display styles from its amounts as they are written in the+journal (excluding cost amounts and amounts in periodic transaction+rules or auto posting rules).  It uses++   * the symbol placement and decimal mark of the first amount seen+   * the digit group marks of the first amount with digit group marks+   * and the maximum number of decimal digits seen across all amounts.++   And as fallback if no applicable amounts are found, it would use a+default style, like '$1000.00' (symbol on the left with no space, period+as decimal mark, and two decimal digits).++   Finally, commodity styles can be overridden by the+'-c/--commodity-style' command line option.+++File: hledger.info,  Node: Rounding,  Prev: Commodity display style,  Up: Amounts++9.12.5 Rounding+---------------++Amounts are stored internally as decimal numbers with up to 255 decimal+places.  They are displayed with their original journal precisions by+print and print-like reports, and rounded to their display precision+(the number of decimal digits specified by the commodity display style)+by other reports.  When rounding, hledger uses banker's rounding (it+rounds to the nearest even digit).  So eg 0.5 displayed with zero+decimal digits appears as "0".+++File: hledger.info,  Node: Costs,  Next: Balance assertions,  Prev: Amounts,  Up: Journal++9.13 Costs+==========++After a posting amount, you can note its cost (when buying) or selling+price (when selling) in another commodity, by writing either '@+UNITPRICE' or '@@ TOTALPRICE' after it.  This indicates a conversion+transaction, where one commodity is exchanged for another.++   (You might also see this called "transaction price" in hledger docs,+discussions, or code; that term was directionally neutral and reminded+that it is a price specific to a transaction, but we now just call it+"cost", with the understanding that the transaction could be a purchase+or a sale.)++   Costs are usually written explicitly with '@' or '@@', but can also+be inferred automatically for simple multi-commodity transactions.+Note, if costs are inferred, the order of postings is significant; the+first posting will have a cost attached, in the commodity of the second.++   As an example, here are several ways to record purchases of a foreign+currency in hledger, using the cost notation either explicitly or+implicitly:++  1. Write the price per unit, as '@ UNITPRICE' after the amount:++     2009/1/1+       assets:euros     €100 @ $1.35  ; one hundred euros purchased at $1.35 each+       assets:dollars                 ; balancing amount is -$135.00++  2. Write the total price, as '@@ TOTALPRICE' after the amount:++     2009/1/1+       assets:euros     €100 @@ $135  ; one hundred euros purchased at $135 for the lot+       assets:dollars++  3. Specify amounts for all postings, using exactly two commodities,+     and let hledger infer the price that balances the transaction.+     Note the effect of posting order: the price is added to first+     posting, making it '€100 @@ $135', as in example 2:++     2009/1/1+       assets:euros     €100          ; one hundred euros purchased+       assets:dollars  $-135          ; for $135++   Amounts can be converted to cost at report time using the '-B/--cost'+flag; this is discussed more in the Cost reporting section.++   Note that the cost normally should be a positive amount, though it's+not required to be.  This can be a little confusing, see discussion at+-infer-market-prices: market prices from transactions.++* Menu:++* Other cost/lot notations::+++File: hledger.info,  Node: Other cost/lot notations,  Up: Costs++9.13.1 Other cost/lot notations+-------------------------------++A slight digression for Ledger and Beancount users.  Ledger has a number+of cost/lot-related notations:++   * '@ UNITCOST' and '@@ TOTALCOST'+        * expresses a conversion rate, as in hledger+        * when buying, also creates a lot than can be selected at+          selling time++   * '(@) UNITCOST' and '(@@) TOTALCOST' (virtual cost)+        * like the above, but also means "this cost was exceptional,+          don't use it when inferring market prices".++   Currently, hledger treats the above like '@' and '@@'; the+parentheses are ignored.++   * '{=FIXEDUNITCOST}' and '{{=FIXEDTOTALCOST}}' (fixed price)+        * when buying, means "this cost is also the fixed price, don't+          let it fluctuate in value reports"++   * '{UNITCOST}' and '{{TOTALCOST}}' (lot price)+        * can be used identically to '@ UNITCOST' and '@@ TOTALCOST',+          also creates a lot+        * when selling, combined with '@ ...', specifies an investment+          lot by its cost basis; does not check if that lot is present++   * and related: '[YYYY/MM/DD]' (lot date)+        * when buying, attaches this acquisition date to the lot+        * when selling, selects a lot by its acquisition date++   * '(SOME TEXT)' (lot note)+        * when buying, attaches this note to the lot+        * when selling, selects a lot by its note++   Currently, hledger accepts any or all of the above in any order after+the posting amount, but ignores them.  (This can break transaction+balancing.)++   For Beancount users, the notation and behaviour is different:++   * '@ UNITCOST' and '@@ TOTALCOST'+        * expresses a cost without creating a lot, as in hledger+        * when buying (augmenting) or selling (reducing) a lot, combined+          with '{...}': documents the cost/selling price (not used for+          transaction balancing)++   * '{UNITCOST}' and '{{TOTALCOST}}'+        * when buying (augmenting), expresses the cost for transaction+          balancing, and also creates a lot with this cost basis+          attached+        * when selling (reducing),+             * selects a lot by its cost basis+             * raises an error if that lot is not present or can not be+               selected unambiguously (depending on booking method+               configured)+             * expresses the selling price for transaction balancing++   Currently, hledger accepts the '{UNITCOST}'/'{{TOTALCOST}}' notation+but ignores it.++   * variations: '{}', '{YYYY-MM-DD}', '{"LABEL"}', '{UNITCOST,+     "LABEL"}', '{UNITCOST, YYYY-MM-DD, "LABEL"}' etc.++   Currently, hledger rejects these.+++File: hledger.info,  Node: Balance assertions,  Next: Posting comments,  Prev: Costs,  Up: Journal++9.14 Balance assertions+=======================++hledger supports Ledger-style balance assertions in journal files.+These look like, for example, '= EXPECTEDBALANCE' following a posting's+amount.  Eg here we assert the expected dollar balance in accounts a and+b after each posting:++2013/1/1+  a   $1  =$1+  b       =$-1++2013/1/2+  a   $1  =$2+  b  $-1  =$-2++   After reading a journal file, hledger will check all balance+assertions and report an error if any of them fail.  Balance assertions+can protect you from, eg, inadvertently disrupting reconciled balances+while cleaning up old entries.  You can disable them temporarily with+the '-I/--ignore-assertions' flag, which can be useful for+troubleshooting or for reading Ledger files.  (Note: this flag currently+does not disable balance assignments, described below).++* Menu:++* Assertions and ordering::+* Assertions and multiple included files::+* Assertions and multiple -f files::+* Assertions and commodities::+* Assertions and prices::+* Assertions and subaccounts::+* Assertions and virtual postings::+* Assertions and auto postings::+* Assertions and precision::+++File: hledger.info,  Node: Assertions and ordering,  Next: Assertions and multiple included files,  Up: Balance assertions++9.14.1 Assertions and ordering+------------------------------++hledger sorts an account's postings and assertions first by date and+then (for postings on the same day) by parse order.  Note this is+different from Ledger, which sorts assertions only by parse order.+(Also, Ledger assertions do not see the accumulated effect of repeated+postings to the same account within a transaction.)++   So, hledger balance assertions keep working if you reorder+differently-dated transactions within the journal.  But if you reorder+same-dated transactions or postings, assertions might break and require+updating.  This order dependence does bring an advantage: precise+control over the order of postings and assertions within a day, so you+can assert intra-day balances.+++File: hledger.info,  Node: Assertions and multiple included files,  Next: Assertions and multiple -f files,  Prev: Assertions and ordering,  Up: Balance assertions++9.14.2 Assertions and multiple included files+---------------------------------------------++Multiple files included with the 'include' directive are processed as if+concatenated into one file, preserving their order and the posting order+within each file.  It means that balance assertions in later files will+see balance from earlier files.++   And if you have multiple postings to an account on the same day,+split across multiple files, and you want to assert the account's+balance on that day, you'll need to put the assertion in the right file+- the last one in the sequence, probably.+++File: hledger.info,  Node: Assertions and multiple -f files,  Next: Assertions and commodities,  Prev: Assertions and multiple included files,  Up: Balance assertions++9.14.3 Assertions and multiple -f files+---------------------------------------++Unlike 'include', when multiple files are specified on the command line+with multiple '-f/--file' options, balance assertions will not see+balance from earlier files.  This can be useful when you do not want+problems in earlier files to disrupt valid assertions in later files.++   If you do want assertions to see balance from earlier files, use+'include', or concatenate the files temporarily.+++File: hledger.info,  Node: Assertions and commodities,  Next: Assertions and prices,  Prev: Assertions and multiple -f files,  Up: Balance assertions++9.14.4 Assertions and commodities+---------------------------------++The asserted balance must be a simple single-commodity amount, and in+fact the assertion checks only this commodity's balance within the+(possibly multi-commodity) account balance.  This is how assertions work+in Ledger also.  We could call this a "partial" balance assertion.++   To assert the balance of more than one commodity in an account, you+can write multiple postings, each asserting one commodity's balance.++   You can make a stronger "total" balance assertion by writing a double+equals sign ('== EXPECTEDBALANCE').  This asserts that there are no+other commodities in the account besides the asserted one (or at least,+that their balance is 0).++2013/1/1+  a   $1+  a    1€+  b  $-1+  c   -1€++2013/1/2  ; These assertions succeed+  a    0  =  $1+  a    0  =   1€+  b    0 == $-1+  c    0 ==  -1€++2013/1/3  ; This assertion fails as 'a' also contains 1€+  a    0 ==  $1++   It's not yet possible to make a complete assertion about a balance+that has multiple commodities.  One workaround is to isolate each+commodity into its own subaccount:++2013/1/1+  a:usd   $1+  a:euro   1€+  b++2013/1/2+  a        0 ==  0+  a:usd    0 == $1+  a:euro   0 ==  1€+++File: hledger.info,  Node: Assertions and prices,  Next: Assertions and subaccounts,  Prev: Assertions and commodities,  Up: Balance assertions++9.14.5 Assertions and prices+----------------------------++Balance assertions ignore costs, and should normally be written without+one:++2019/1/1+  (a)     $1 @ €1 = $1++   We do allow prices to be written there, however, and print shows+them, even though they don't affect whether the assertion passes or+fails.  This is for backward compatibility (hledger's close command used+to generate balance assertions with prices), and because balance+_assignments_ do use them (see below).+++File: hledger.info,  Node: Assertions and subaccounts,  Next: Assertions and virtual postings,  Prev: Assertions and prices,  Up: Balance assertions++9.14.6 Assertions and subaccounts+---------------------------------++The balance assertions above ('=' and '==') do not count the balance+from subaccounts; they check the account's exclusive balance only.  You+can assert the balance including subaccounts by writing '=*' or '==*',+eg:++2019/1/1+  equity:opening balances+  checking:a       5+  checking:b       5+  checking         1  ==* 11+++File: hledger.info,  Node: Assertions and virtual postings,  Next: Assertions and auto postings,  Prev: Assertions and subaccounts,  Up: Balance assertions++9.14.7 Assertions and virtual postings+--------------------------------------++Balance assertions always consider both real and virtual postings; they+are not affected by the '--real/-R' flag or 'real:' query.+++File: hledger.info,  Node: Assertions and auto postings,  Next: Assertions and precision,  Prev: Assertions and virtual postings,  Up: Balance assertions++9.14.8 Assertions and auto postings+-----------------------------------++Balance assertions _are_ affected by the '--auto' flag, which generates+auto postings, which can alter account balances.  Because auto postings+are optional in hledger, accounts affected by them effectively have two+balances.  But balance assertions can only test one or the other of+these.  So to avoid making fragile assertions, either:++   * assert the balance calculated with '--auto', and always use+     '--auto' with that file+   * or assert the balance calculated without '--auto', and never use+     '--auto' with that file+   * or avoid balance assertions on accounts affected by auto postings+     (or avoid auto postings entirely).+++File: hledger.info,  Node: Assertions and precision,  Prev: Assertions and auto postings,  Up: Balance assertions++9.14.9 Assertions and precision+-------------------------------++Balance assertions compare the exactly calculated amounts, which are not+always what is shown by reports.  Eg a commodity directive may limit the+display precision, but this will not affect balance assertions.  Balance+assertion failure messages show exact amounts.+++File: hledger.info,  Node: Posting comments,  Next: Tags,  Prev: Balance assertions,  Up: Journal++9.15 Posting comments+=====================++Text following ';', at the end of a posting line, and/or on indented+lines immediately below it, form comments for that posting.  They are+reproduced by 'print' but otherwise ignored, except they may contain+tags, which are not ignored.++2012-01-01+    expenses   1  ; a comment for posting 1+    assets+    ; a comment for posting 2+    ; a second comment line for posting 2+++File: hledger.info,  Node: Tags,  Next: Directives,  Prev: Posting comments,  Up: Journal++9.16 Tags+=========++Tags are a way to add extra labels or labelled data to transactions,+postings, or accounts, which you can then search or pivot on.++   They are written as a word (optionally hyphenated) immediately+followed by a full colon, in a transaction or posting or account+directive's comment.  (This is an exception to the usual rule that+things in comments are ignored.)  Eg, here four different tags are+recorded: one on the checking account, two on the transaction, and one+on the expenses posting:++account assets:checking         ; accounttag:++2017/1/16 bought groceries      ; transactiontag-1:+    ; transactiontag-2:+    assets:checking        $-1+    expenses:food           $1  ; postingtag:++   Postings also inherit tags from their transaction and their account.+And transactions also acquire tags from their postings (and postings'+accounts).  So in the example above, the expenses posting effectively+has all four tags (by inheriting from account and transaction), and the+transaction also has all four tags (by acquiring from the expenses+posting).++   You can list tag names with 'hledger tags [NAMEREGEX]', or match by+tag name with a 'tag:NAMEREGEX' query.++* Menu:++* Tag values::+++File: hledger.info,  Node: Tag values,  Up: Tags++9.16.1 Tag values+-----------------++Tags can have a value, which is any text after the colon up until a+comma or end of line (with surrounding whitespace removed).  Note this+means that hledger tag values can not contain commas.  Eg in the+following posting, the three tags' values are "value 1", "value 2", and+"" (empty) respectively:++    expenses:food   $10    ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz++   Note that tags can be repeated, and are additive rather than+overriding: when the same tag name is seen again with a new value, the+new name:value pair is added to the tags.  (It is not possible to+override a tag's value or remove a tag.)++   You can list a tag's values with 'hledger tags TAGNAME --values', or+match by tag value with a 'tag:NAMEREGEX=VALUEREGEX' query.+++File: hledger.info,  Node: Directives,  Next: account directive,  Prev: Tags,  Up: Journal++9.17 Directives+===============++Besides transactions, there is something else you can put in a 'journal'+file: directives.  These are declarations, beginning with a keyword,+that modify hledger's behaviour.  Some directives can have more specific+subdirectives, indented below them.  hledger's directives are similar to+Ledger's in many cases, but there are also many differences.  Directives+are not required, but can be useful.  Here are the main directives:++purpose                                   directive+--------------------------------------------------------------------------+*READING DATA:*+Rewrite account names                     'alias'+Comment out sections of the file          'comment'+Declare file's decimal mark, to help      'decimal-mark'+parse amounts accurately+Include other data files                  'include'+*GENERATING DATA:*+Generate recurring transactions or        '~'+budget goals+Generate extra postings on existing       '='+transactions+*CHECKING FOR ERRORS:*+Define valid entities to provide more     'account', 'commodity',+error checking                            'payee', 'tag'+*REPORTING:*+Declare accounts' type and display        'account'+order+Declare commodity display styles          'commodity'+Declare market prices                     'P'++* Menu:++* Directives and multiple files::+* Directive effects::+++File: hledger.info,  Node: Directives and multiple files,  Next: Directive effects,  Up: Directives++9.17.1 Directives and multiple files+------------------------------------++Directives vary in their scope, ie which journal entries and which input+files they affect.  Most often, a directive will affect the following+entries and included files if any, until the end of the current file -+and no further.  You might find this inconvenient!  For example, 'alias'+directives do not affect parent or sibling files.  But there are usually+workarounds; for example, put 'alias' directives in your top-most file,+before including other files.++   The restriction, though it may be annoying at first, is in a good+cause; it allows reports to be stable and deterministic, independent of+the order of input.  Without it, reports could show different numbers+depending on the order of -f options, or the positions of include+directives in your files.+++File: hledger.info,  Node: Directive effects,  Prev: Directives and multiple files,  Up: Directives++9.17.2 Directive effects+------------------------++Here are all hledger's directives, with their effects and scope+summarised - nine main directives, plus four others which we consider+non-essential:++directivewhat it does                                                   ends+                                                                        at+                                                                        file+                                                                        end?+---------------------------------------------------------------------------+*'account'*Declares an account, for checking all entries in all files; andN+     its display order and type.  Subdirectives: any text, ignored.+*'alias'*Rewrites account names, in following entries until end of      Y+     current file or 'end aliases'.  Command line equivalent:+     '--alias'+*'comment'*Ignores part of the journal file, until end of current file orY+     'end comment'.+*'commodity'*Declares up to four things: 1.  a commodity symbol, for checkingN,Y,N,N+     all amounts in all files 2.  the decimal mark for parsing+     amounts of this commodity, in the following entries until end of+     current file (if there is no 'decimal-mark' directive) 3.  and+     the display style for amounts of this commodity 4.  which is+     also the precision to use for balanced-transaction checking in+     this commodity.  Takes precedence over 'D'.  Subdirectives:+     'format' (Ledger-compatible syntax).  Command line equivalent:+     '-c/--commodity-style'+*'decimal-mark'*Declares the decimal mark, for parsing amounts of all   Y+     commodities in following entries until next 'decimal-mark' or+     end of current file.  Included files can override.  Takes+     precedence over 'commodity' and 'D'.+*'include'*Includes entries and directives from another file, as if theyN+     were written inline.  Command line alternative: multiple+     '-f/--file'+*'payee'*Declares a payee name, for checking all entries in all files.  N+*'P'*Declares the market price of a commodity on some date, for value   N+     reports.+*'~'*Declares a periodic transaction rule that generates future         N+(tilde)transactions with '--forecast' and budget goals with 'balance+     --budget'.+Other+syntax:+*'applyPrepends a common parent account to all account names, in        Y+account'*following entries until end of current file or 'end apply+     account'.+*'D'*Sets a default commodity to use for no-symbol amounts;and, if      Y,Y,N,N+     there is no 'commodity' directive for this commodity: its+     decimal mark, balancing precision, and display style, as above.+*'Y'*Sets a default year to use for any yearless dates, in following    Y+     entries until end of current file.+*'='*Declares an auto posting rule that generates extra postings on     partly+(equals)matched transactions with '--auto', in current, parent, and+     child files (but not sibling files, see #1212).+*OtherOther directives from Ledger's file format are accepted but+Ledgerignored.+directives*+++File: hledger.info,  Node: account directive,  Next: alias directive,  Prev: Directives,  Up: Journal++9.18 'account' directive+========================++'account' directives can be used to declare accounts (ie, the places+that amounts are transferred from and to).  Though not required, these+declarations can provide several benefits:++   * They can document your intended chart of accounts, providing a+     reference.+   * In strict mode, they restrict which accounts may be posted to by+     transactions, which helps detect typos.+   * They control account display order in reports, allowing+     non-alphabetic sorting (eg Revenues to appear above Expenses).+   * They help with account name completion (in hledger add,+     hledger-web, hledger-iadd, ledger-mode, etc.)+   * They can store additional account information as comments, or as+     tags which can be used to filter or pivot reports.+   * They can help hledger know your accounts' types (asset, liability,+     equity, revenue, expense), affecting reports like balancesheet and+     incomestatement.++   They are written as the word 'account' followed by a hledger-style+account name, eg:++account assets:bank:checking++   Note, however, that accounts declared in account directives are not+allowed to have surrounding brackets and parentheses, unlike accounts+used in postings.  So the following journal will not parse:++account (assets:bank:checking)++* Menu:++* Account comments::+* Account subdirectives::+* Account error checking::+* Account display order::+* Account types::+++File: hledger.info,  Node: Account comments,  Next: Account subdirectives,  Up: account directive++9.18.1 Account comments+-----------------------++Text following *two or more spaces* and ';' at the end of an account+directive line, and/or following ';' on indented lines immediately below+it, form comments for that account.  They are ignored except they may+contain tags, which are not ignored.++   The two-space requirement for same-line account comments is because+';' is allowed in account names.++account assets:bank:checking    ; same-line comment, at least 2 spaces before the semicolon+  ; next-line comment+  ; some tags - type:A, acctnum:12345+++File: hledger.info,  Node: Account subdirectives,  Next: Account error checking,  Prev: Account comments,  Up: account directive++9.18.2 Account subdirectives+----------------------------++Ledger-style indented subdirectives are also accepted, but currently+ignored:++account assets:bank:checking+  format subdirective is ignored+++File: hledger.info,  Node: Account error checking,  Next: Account display order,  Prev: Account subdirectives,  Up: account directive++9.18.3 Account error checking+-----------------------------++By default, accounts need not be declared; they come into existence when+a posting references them.  This is convenient, but it means hledger+can't warn you when you mis-spell an account name in the journal.+Usually you'll find that error later, as an extra account in balance+reports, or an incorrect balance when reconciling.++   In strict mode, enabled with the '-s'/'--strict' flag, hledger will+report an error if any transaction uses an account name that has not+been declared by an account directive.  Some notes:++   * The declaration is case-sensitive; transactions must use the+     correct account name capitalisation.+   * The account directive's scope is "whole file and below" (see+     directives).  This means it affects all of the current file, and+     any files it includes, but not parent or sibling files.  The+     position of account directives within the file does not matter,+     though it's usual to put them at the top.+   * Accounts can only be declared in 'journal' files, but will affect+     included files of all types.+   * It's currently not possible to declare "all possible subaccounts"+     with a wildcard; every account posted to must be declared.+++File: hledger.info,  Node: Account display order,  Next: Account types,  Prev: Account error checking,  Up: account directive++9.18.4 Account display order+----------------------------++The order in which account directives are written influences the order+in which accounts appear in reports, hledger-ui, hledger-web etc.  By+default accounts appear in alphabetical order, but if you add these+account directives to the journal file:++account assets+account liabilities+account equity+account revenues+account expenses++   those accounts will be displayed in declaration order:++$ hledger accounts -1+assets+liabilities+equity+revenues+expenses++   Any undeclared accounts are displayed last, in alphabetical order.++   Sorting is done at each level of the account tree, within each group+of sibling accounts under the same parent.  And currently, this+directive:++account other:zoo++   would influence the position of 'zoo' among 'other''s subaccounts,+but not the position of 'other' among the top-level accounts.  This+means:++   * you will sometimes declare parent accounts (eg 'account other'+     above) that you don't intend to post to, just to customize their+     display order+   * sibling accounts stay together (you couldn't display 'x:y' in+     between 'a:b' and 'a:c').+++File: hledger.info,  Node: Account types,  Prev: Account display order,  Up: account directive++9.18.5 Account types+--------------------++hledger knows that accounts come in several types: assets, liabilities,+expenses and so on.  This enables easy reports like balancesheet and+incomestatement, and filtering by account type with the 'type:' query.++   As a convenience, hledger will detect these account types+automatically if you are using common english-language top-level account+names (described below).  But generally we recommend you declare types+explicitly, by adding a 'type:' tag to your top-level account+directives.  Subaccounts will inherit the type of their parent.  The+tag's value should be one of the five main account types:++   * 'A' or 'Asset' (things you own)+   * 'L' or 'Liability' (things you owe)+   * 'E' or 'Equity' (investment/ownership; balanced counterpart of+     assets & liabilities)+   * 'R' or 'Revenue' (what you received money from, AKA income;+     technically part of Equity)+   * 'X' or 'Expense' (what you spend money on; technically part of+     Equity)++   or, it can be (these are used less often):++   * 'C' or 'Cash' (a subtype of Asset, indicating liquid assets for the+     cashflow report)+   * 'V' or 'Conversion' (a subtype of Equity, for conversions (see Cost+     reporting).)++   Here is a typical set of account type declarations:++account assets             ; type: A+account liabilities        ; type: L+account equity             ; type: E+account revenues           ; type: R+account expenses           ; type: X++account assets:bank        ; type: C+account assets:cash        ; type: C++account equity:conversion  ; type: V++   Here are some tips for working with account types.++   * The rules for inferring types from account names are as follows.+     These are just a convenience that sometimes help new users get+     going; if they don't work for you, just ignore them and declare+     your account types.  See also Regular expressions.++     If account's name contains this (CI) regular expression:            | its type is:+     --------------------------------------------------------------------|-------------+     ^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|current)(:|$) | Cash+     ^assets?(:|$)                                                       | Asset+     ^(debts?|liabilit(y|ies))(:|$)                                      | Liability+     ^equity:(trad(e|ing)|conversion)s?(:|$)                             | Conversion+     ^equity(:|$)                                                        | Equity+     ^(income|revenue)s?(:|$)                                            | Revenue+     ^expenses?(:|$)                                                     | Expense++   * If you declare any account types, it's a good idea to declare an+     account for all of the account types, because a mixture of declared+     and name-inferred types can disrupt certain reports.++   * Certain uses of account aliases can disrupt account types.  See+     Rewriting accounts > Aliases and account types.++   * As mentioned above, subaccounts will inherit a type from their+     parent account.  More precisely, an account's type is decided by+     the first of these that exists:++       1. A 'type:' declaration for this account.+       2. A 'type:' declaration in the parent accounts above it,+          preferring the nearest.+       3. An account type inferred from this account's name.+       4. An account type inferred from a parent account's name,+          preferring the nearest parent.+       5. Otherwise, it will have no type.++   * For troubleshooting, you can list accounts and their types with:++     $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES]+++File: hledger.info,  Node: alias directive,  Next: commodity directive,  Prev: account directive,  Up: Journal++9.19 'alias' directive+======================++You can define account alias rules which rewrite your account names, or+parts of them, before generating reports.  This can be useful for:++   * expanding shorthand account names to their full form, allowing+     easier data entry and a less verbose journal+   * adapting old journals to your current chart of accounts+   * experimenting with new account organisations, like a new hierarchy+   * combining two accounts into one, eg to see their sum or difference+     on one line+   * customising reports++   Account aliases also rewrite account names in account directives.+They do not affect account names being entered via hledger add or+hledger-web.++   Account aliases are very powerful.  They are generally easy to use+correctly, but you can also generate invalid account names with them;+more on this below.++   See also Rewrite account names.++* Menu:++* Basic aliases::+* Regex aliases::+* Combining aliases::+* Aliases and multiple files::+* end aliases directive::+* Aliases can generate bad account names::+* Aliases and account types::+++File: hledger.info,  Node: Basic aliases,  Next: Regex aliases,  Up: alias directive++9.19.1 Basic aliases+--------------------++To set an account alias, use the 'alias' directive in your journal file.+This affects all subsequent journal entries in the current file or its+included files (but note: not sibling or parent files).  The spaces+around the = are optional:++alias OLD = NEW++   Or, you can use the '--alias 'OLD=NEW'' option on the command line.+This affects all entries.  It's useful for trying out aliases+interactively.++   OLD and NEW are case sensitive full account names.  hledger will+replace any occurrence of the old account name with the new one.+Subaccounts are also affected.  Eg:++alias checking = assets:bank:wells fargo:checking+; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"+++File: hledger.info,  Node: Regex aliases,  Next: Combining aliases,  Prev: Basic aliases,  Up: alias directive++9.19.2 Regex aliases+--------------------++There is also a more powerful variant that uses a regular expression,+indicated by wrapping the pattern in forward slashes.  (This is the only+place where hledger requires forward slashes around a regular+expression.)++   Eg:++alias /REGEX/ = REPLACEMENT++   or:++$ hledger --alias '/REGEX/=REPLACEMENT' ...++   Any part of an account name matched by REGEX will be replaced by+REPLACEMENT. REGEX is case-insensitive as usual.++   If you need to match a forward slash, escape it with a backslash, eg+'/\/=:'.++   If REGEX contains parenthesised match groups, these can be referenced+by the usual backslash and number in REPLACEMENT:++alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3+; rewrites "assets:bank:wells fargo:checking" to  "assets:wells fargo checking"++   REPLACEMENT continues to the end of line (or on command line, to end+of option argument), so it can contain trailing whitespace.+++File: hledger.info,  Node: Combining aliases,  Next: Aliases and multiple files,  Prev: Regex aliases,  Up: alias directive++9.19.3 Combining aliases+------------------------++You can define as many aliases as you like, using journal directives+and/or command line options.++   Recursive aliases - where an account name is rewritten by one alias,+then by another alias, and so on - are allowed.  Each alias sees the+effect of previously applied aliases.++   In such cases it can be important to understand which aliases will be+applied and in which order.  For (each account name in) each journal+entry, we apply:++  1. 'alias' directives preceding the journal entry, most recently+     parsed first (ie, reading upward from the journal entry, bottom to+     top)+  2. '--alias' options, in the order they appeared on the command line+     (left to right).++   In other words, for (an account name in) a given journal entry:++   * the nearest alias declaration before/above the entry is applied+     first+   * the next alias before/above that will be be applied next, and so on+   * aliases defined after/below the entry do not affect it.++   This gives nearby aliases precedence over distant ones, and helps+provide semantic stability - aliases will keep working the same way+independent of which files are being read and in which order.++   In case of trouble, adding '--debug=6' to the command line will show+which aliases are being applied when.+++File: hledger.info,  Node: Aliases and multiple files,  Next: end aliases directive,  Prev: Combining aliases,  Up: alias directive++9.19.4 Aliases and multiple files+---------------------------------++As explained at Directives and multiple files, 'alias' directives do not+affect parent or sibling files.  Eg in this command,++hledger -f a.aliases -f b.journal++   account aliases defined in a.aliases will not affect b.journal.+Including the aliases doesn't work either:++include a.aliases++2023-01-01  ; not affected by a.aliases+  foo  1+  bar++   This means that account aliases should usually be declared at the+start of your top-most file, like this:++alias foo=Foo+alias bar=Bar++2023-01-01  ; affected by aliases above+  foo  1+  bar++include c.journal  ; also affected+++File: hledger.info,  Node: end aliases directive,  Next: Aliases can generate bad account names,  Prev: Aliases and multiple files,  Up: alias directive++9.19.5 'end aliases' directive+------------------------------++You can clear (forget) all currently defined aliases (seen in the+journal so far, or defined on the command line) with this directive:++end aliases+++File: hledger.info,  Node: Aliases can generate bad account names,  Next: Aliases and account types,  Prev: end aliases directive,  Up: alias directive++9.19.6 Aliases can generate bad account names+---------------------------------------------++Be aware that account aliases can produce malformed account names, which+could cause confusing reports or invalid 'print' output.  For example,+you could erase all account names:++2021-01-01+  a:aa     1+  b++$ hledger print --alias '/.*/='+2021-01-01+                   1++   The above 'print' output is not a valid journal.  Or you could insert+an illegal double space, causing 'print' output that would give a+different journal when reparsed:++2021-01-01+  old    1+  other++$ hledger print --alias old="new  USD" | hledger -f- print+2021-01-01+    new             USD 1+    other+++File: hledger.info,  Node: Aliases and account types,  Prev: Aliases can generate bad account names,  Up: alias directive++9.19.7 Aliases and account types+--------------------------------++If an account with a type declaration (see Declaring accounts > Account+types) is renamed by an alias, normally the account type remains in+effect.++   However, renaming in a way that reshapes the account tree (eg+renaming parent accounts but not their children, or vice versa) could+prevent child accounts from inheriting the account type of their+parents.++   Secondly, if an account's type is being inferred from its name,+renaming it by an alias could prevent or alter that.++   If you are using account aliases and the 'type:' query is not+matching accounts as you expect, try troubleshooting with the accounts+command, eg something like:++$ hledger accounts --alias assets=bassetts type:a+++File: hledger.info,  Node: commodity directive,  Next: decimal-mark directive,  Prev: alias directive,  Up: Journal++9.20 'commodity' directive+==========================++The 'commodity' directive performs several functions:++  1. It declares which commodity symbols may be used in the journal,+     enabling useful error checking with strict mode or the check+     command.  (See Commodity error checking below.)++  2. It declares the precision with which this commodity's amounts+     should be compared when checking for balanced transactions.++  3. It declares how this commodity's amounts should be displayed, eg+     their symbol placement, digit group mark if any, digit group sizes,+     decimal mark (period or comma), and the number of decimal places.+     (See Commodity display style above.)++  4. It sets which decimal mark (period or comma) to expect when parsing+     subsequent amounts in this commodity (if there is no 'decimal-mark'+     directive in effect.  See Decimal marks, digit group marks above.+     For related dev discussion, see #793.)++   Declaring commodities solves several common parsing/display problems,+so we recommend it.  Generally you should put 'commodity' directives at+the top of your journal file (because function 4 is position-sensitive).++* Menu:++* Commodity directive syntax::+* Commodity error checking::+++File: hledger.info,  Node: Commodity directive syntax,  Next: Commodity error checking,  Up: commodity directive++9.20.1 Commodity directive syntax+---------------------------------++A commodity directive is normally the word 'commodity' followed by a+sample amount (and optionally a comment).  Only the amount's symbol and+format is significant.  Eg:++commodity $1000.00+commodity 1.000,00 EUR+commodity 1 000 000.0000   ; the no-symbol commodity++   Commodities do not have tags (tags in the comment will be ignored).++   A commodity directive's sample amount must always include a period or+comma decimal mark (this rule helps disambiguate decimal marks and digit+group marks).  If you don't want to show any decimal digits, write the+decimal mark at the end:++commodity 1000. AAAA       ; show AAAA with no decimals++   Commodity symbols containing spaces, numbers, or punctuation must be+enclosed in double quotes, as usual:++commodity 1.0000 "AAAA 2023"++   Commodity directives normally include a sample amount, but can+declare only a symbol (ie, just function 1 above):++commodity $+commodity INR+commodity "AAAA 2023"+commodity ""               ; the no-symbol commodity++   Commodity directives may also be written with an indented 'format'+subdirective, as in Ledger.  The symbol is repeated and must be the same+in both places.  Other subdirectives are currently ignored:++; display indian rupees with currency name on the left,+; thousands, lakhs and crores comma-separated,+; period as decimal point, and two decimal places.+commodity INR+  format INR 1,00,00,000.00+  an unsupported subdirective  ; ignored by hledger+++File: hledger.info,  Node: Commodity error checking,  Prev: Commodity directive syntax,  Up: commodity directive++9.20.2 Commodity error checking+-------------------------------++In strict mode ('-s'/'--strict') (or when you run 'hledger check+commodities'), hledger will report an error if an undeclared commodity+symbol is used.  (With one exception: zero amounts are always allowed to+have no commodity symbol.)  It works like account error checking+(described above).+++File: hledger.info,  Node: decimal-mark directive,  Next: include directive,  Prev: commodity directive,  Up: Journal++9.21 'decimal-mark' directive+=============================++You can use a 'decimal-mark' directive - usually one per file, at the+top of the file - to declare which character represents a decimal mark+when parsing amounts in this file.  It can look like++decimal-mark .++   or++decimal-mark ,++   This prevents any ambiguity when parsing numbers in the file, so we+recommend it, especially if the file contains digit group marks (eg+thousands separators).+++File: hledger.info,  Node: include directive,  Next: P directive,  Prev: decimal-mark directive,  Up: Journal++9.22 'include' directive+========================++You can pull in the content of additional files by writing an include+directive, like this:++include FILEPATH++   Only journal files can include, and only journal, timeclock or+timedot files can be included (not CSV files, currently).++   If the file path does not begin with a slash, it is relative to the+current file's folder.++   A tilde means home directory, eg: 'include ~/main.journal'.++   The path may contain glob patterns to match multiple files, eg:+'include *.journal'.++   There is limited support for recursive wildcards: '**/' (the slash is+required) matches 0 or more subdirectories.  It's not super convenient+since you have to avoid include cycles and including directories, but+this can be done, eg: 'include */**/*.journal'.++   The path may also be prefixed to force a specific file format,+overriding the file extension (as described in Data formats): 'include+timedot:~/notes/2023*.md'.+++File: hledger.info,  Node: P directive,  Next: payee directive,  Prev: include directive,  Up: Journal++9.23 'P' directive+==================++The 'P' directive declares a market price, which is a conversion rate+between two commodities on a certain date.  This allows value reports to+convert amounts of one commodity to their value in another, on or after+that date.  These prices are often obtained from a stock exchange,+cryptocurrency exchange, the or foreign exchange market.++   The format is:++P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT++   DATE is a simple date, COMMODITY1SYMBOL is the symbol of the+commodity being priced, and COMMODITY2AMOUNT is the amount (symbol and+quantity) of commodity 2 that one unit of commodity 1 is worth on this+date.  Examples:++# one euro was worth $1.35 from 2009-01-01 onward:+P 2009-01-01 € $1.35++# and $1.40 from 2010-01-01 onward:+P 2010-01-01 € $1.40++   The '-V', '-X' and '--value' flags use these market prices to show+amount values in another commodity.  See Value reporting.+++File: hledger.info,  Node: payee directive,  Next: tag directive,  Prev: P directive,  Up: Journal++9.24 'payee' directive+======================++'payee PAYEE NAME'++   This directive can be used to declare a limited set of payees which+may appear in transaction descriptions.  The "payees" check will report+an error if any transaction refers to a payee that has not been+declared.  Eg:++payee Whole Foods    ; a comment++   Payees do not have tags (tags in the comment will be ignored).++   To declare the empty payee name, use '""'.++payee ""++   Ledger-style indented subdirectives, if any, are currently ignored.+++File: hledger.info,  Node: tag directive,  Next: Periodic transactions,  Prev: payee directive,  Up: Journal++9.25 'tag' directive+====================++'tag TAGNAME'++   This directive can be used to declare a limited set of tag names+allowed in tags.  TAGNAME should be a valid tag name (no spaces).  Eg:++tag  item-id++   Any indented subdirectives are currently ignored.++   The "tags" check will report an error if any undeclared tag name is+used.  It is quite easy to accidentally create a tag through normal use+of colons in comments(#comments]; if you want to prevent this, you can+declare and check your tags .+++File: hledger.info,  Node: Periodic transactions,  Next: Auto postings,  Prev: tag directive,  Up: Journal++9.26 Periodic transactions+==========================++The '~' directive declares recurring transactions.  Such directives+allow hledger to generate temporary future transactions (visible in+reports, not in the journal file) to help with forecasting or budgeting.++   Periodic transactions can be a little tricky, so before you use them,+read this whole section, or at least these tips:++  1. Two spaces accidentally added or omitted will cause you trouble -+     read about this below.+  2. For troubleshooting, show the generated transactions with 'hledger+     print --forecast tag:generated' or 'hledger register --forecast+     tag:generated'.+  3. Forecasted transactions will begin only after the last+     non-forecasted transaction's date.+  4. Forecasted transactions will end 6 months from today, by default.+     See below for the exact start/end rules.+  5. period expressions can be tricky.  Their documentation needs+     improvement, but is worth studying.+  6. Some period expressions with a repeating interval must begin on a+     natural boundary of that interval.  Eg in 'weekly from DATE', DATE+     must be a monday.  '~ weekly from 2019/10/1' (a tuesday) will give+     an error.+  7. Other period expressions with an interval are automatically+     expanded to cover a whole number of that interval.  (This is done+     to improve reports, but it also affects periodic transactions.+     Yes, it's a bit inconsistent with the above.)  Eg: '~ every 10th+     day of month from 2023/01', which is equivalent to '~ every 10th+     day of month from 2023/01/01', will be adjusted to start on+     2019/12/10.++* Menu:++* Periodic rule syntax::+* Periodic rules and relative dates::+* Two spaces between period expression and description!::+++File: hledger.info,  Node: Periodic rule syntax,  Next: Periodic rules and relative dates,  Up: Periodic transactions++9.26.1 Periodic rule syntax+---------------------------++A periodic transaction rule looks like a normal journal entry, with the+date replaced by a tilde ('~') followed by a period expression+(mnemonic: '~' looks like a recurring sine wave.):++# every first of month+~ monthly+    expenses:rent          $2000+    assets:bank:checking++# every 15th of month in 2023's first quarter:+~ monthly from 2023-04-15 to 2023-06-16+    expenses:utilities          $400+    assets:bank:checking++   The period expression is the same syntax used for specifying+multi-period reports, just interpreted differently; there, it specifies+report periods; here it specifies recurrence dates (the periods' start+dates).+++File: hledger.info,  Node: Periodic rules and relative dates,  Next: Two spaces between period expression and description!,  Prev: Periodic rule syntax,  Up: Periodic transactions++9.26.2 Periodic rules and relative dates+----------------------------------------++Partial or relative dates (like '12/31', '25', 'tomorrow', 'last week',+'next quarter') are usually not recommended in periodic rules, since the+results will change as time passes.  If used, they will be interpreted+relative to, in order of preference:++  1. the first day of the default year specified by a recent 'Y'+     directive+  2. or the date specified with '--today'+  3. or the date on which you are running the report.++   They will not be affected at all by report period or forecast period+dates.+++File: hledger.info,  Node: Two spaces between period expression and description!,  Prev: Periodic rules and relative dates,  Up: Periodic transactions++9.26.3 Two spaces between period expression and description!+------------------------------------------------------------++If the period expression is followed by a transaction description, these+must be separated by *two or more spaces*.  This helps hledger know+where the period expression ends, so that descriptions can not+accidentally alter their meaning, as in this example:++; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2023"+;               ||+;               vv+~ every 2 months  in 2023, we will review+    assets:bank:checking   $1500+    income:acme inc++   So,++   * Do write two spaces between your period expression and your+     transaction description, if any.+   * Don't accidentally write two spaces in the middle of your period+     expression.+++File: hledger.info,  Node: Auto postings,  Next: Other syntax,  Prev: Periodic transactions,  Up: Journal++9.27 Auto postings+==================++The '=' directive declares a rule for generating temporary extra+postings on transactions.  Wherever the rule matches an existing+posting, it can add one or more companion postings below that one,+optionally influenced by the matched posting's amount.  This can be+useful for generating tax postings with a standard percentage, for+example.++   Note that depending on generated data is not ideal for financial+records (it's less portable, less future-proof, less auditable by+others, and less robust, since other features like balance assertions+will depend on using or not using '--auto').++   An auto posting rule looks a bit like a transaction:++= QUERY+    ACCOUNT  AMOUNT+    ...+    ACCOUNT  [AMOUNT]++   except the first line is an equals sign (mnemonic: '=' suggests+matching), followed by a query (which matches existing postings), and+each "posting" line describes a posting to be generated, and the posting+amounts can be:++   * a normal amount with a commodity symbol, eg '$2'.  This will be+     used as-is.+   * a number, eg '2'.  The commodity symbol (if any) from the matched+     posting will be added to this.+   * a numeric multiplier, eg '*2' (a star followed by a number N). The+     matched posting's amount (and total price, if any) will be+     multiplied by N.+   * a multiplier with a commodity symbol, eg '*$2' (a star, number N,+     and symbol S). The matched posting's amount will be multiplied by+     N, and its commodity symbol will be replaced with S.++   Any query term containing spaces must be enclosed in single or double+quotes, as on the command line.  Eg, note the quotes around the second+query term below:++= expenses:groceries 'expenses:dining out'+    (budget:funds:dining out)                 *-1++   Some examples:++; every time I buy food, schedule a dollar donation+= expenses:food+    (liabilities:charity)   $-1++; when I buy a gift, also deduct that amount from a budget envelope subaccount+= expenses:gifts+    assets:checking:gifts  *-1+    assets:checking         *1++2017/12/1+  expenses:food    $10+  assets:checking++2017/12/14+  expenses:gifts   $20+  assets:checking++$ hledger print --auto+2017-12-01+    expenses:food              $10+    assets:checking+    (liabilities:charity)      $-1++2017-12-14+    expenses:gifts             $20+    assets:checking+    assets:checking:gifts     -$20+    assets:checking            $20++* Menu:++* Auto postings and multiple files::+++File: hledger.info,  Node: Auto postings and multiple files,  Up: Auto postings++9.27.1 Auto postings and multiple files+---------------------------------------++An auto posting rule can affect any transaction in the current file, or+in any parent file or child file.  Note, currently it will not affect+sibling files (when multiple '-f'/'--file' are used - see #1212).++* Menu:++* Auto postings and dates::+* Auto postings and transaction balancing / inferred amounts / balance assertions::+* Auto posting tags::+* Auto postings on forecast transactions only::+++File: hledger.info,  Node: Auto postings and dates,  Next: Auto postings and transaction balancing / inferred amounts / balance assertions,  Up: Auto postings and multiple files++9.27.1.1 Auto postings and dates+................................++A posting date (or secondary date) in the matched posting, or (taking+precedence) a posting date in the auto posting rule itself, will also be+used in the generated posting.+++File: hledger.info,  Node: Auto postings and transaction balancing / inferred amounts / balance assertions,  Next: Auto posting tags,  Prev: Auto postings and dates,  Up: Auto postings and multiple files++9.27.1.2 Auto postings and transaction balancing / inferred+...........................................................++amounts / balance assertions Currently, auto postings are added:++   * after missing amounts are inferred, and transactions are checked+     for balancedness,+   * but before balance assertions are checked.++   Note this means that journal entries must be balanced both before and+after auto postings are added.  This changed in hledger 1.12+; see #893+for background.++   This also means that you cannot have more than one auto-posting with+a missing amount applied to a given transaction, as it will be unable to+infer amounts.+++File: hledger.info,  Node: Auto posting tags,  Next: Auto postings on forecast transactions only,  Prev: Auto postings and transaction balancing / inferred amounts / balance assertions,  Up: Auto postings and multiple files++9.27.1.3 Auto posting tags+..........................++Automated postings will have some extra tags:++   * 'generated-posting:= QUERY' - shows this was generated by an auto+     posting rule, and the query+   * '_generated-posting:= QUERY' - a hidden tag, which does not appear+     in hledger's output.  This can be used to match postings generated+     "just now", rather than generated in the past and saved to the+     journal.++   Also, any transaction that has been changed by auto posting rules+will have these tags added:++   * 'modified:' - this transaction was modified+   * '_modified:' - a hidden tag not appearing in the comment; this+     transaction was modified "just now".+++File: hledger.info,  Node: Auto postings on forecast transactions only,  Prev: Auto posting tags,  Up: Auto postings and multiple files++9.27.1.4 Auto postings on forecast transactions only+....................................................++Tip: you can can make auto postings that will apply to forecast+transactions but not recorded transactions, by adding+'tag:_generated-transaction' to their QUERY. This can be useful when+generating new journal entries to be saved in the journal.+++File: hledger.info,  Node: Other syntax,  Prev: Auto postings,  Up: Journal++9.28 Other syntax+=================++hledger journal format supports quite a few other features, mainly to+make interoperating with or converting from Ledger easier.  Note some of+the features below are powerful and can be useful in special cases, but+in general, features in this section are considered less important or+even not recommended for most users.  Downsides are mentioned to help+you decide if you want to use them.++* Menu:++* Balance assignments::+* Bracketed posting dates::+* D directive::+* apply account directive::+* Y directive::+* Secondary dates::+* Star comments::+* Valuation expressions::+* Virtual postings::+* Other Ledger directives::+++File: hledger.info,  Node: Balance assignments,  Next: Bracketed posting dates,  Up: Other syntax++9.28.1 Balance assignments+--------------------------++Ledger-style balance assignments are also supported.  These are like+balance assertions, but with no posting amount on the left side of the+equals sign; instead it is calculated automatically so as to satisfy the+assertion.  This can be a convenience during data entry, eg when setting+opening balances:++; starting a new journal, set asset account balances+2016/1/1 opening balances+  assets:checking            = $409.32+  assets:savings             = $735.24+  assets:cash                 = $42+  equity:opening balances++   or when adjusting a balance to reality:++; no cash left; update balance, record any untracked spending as a generic expense+2016/1/15+  assets:cash    = $0+  expenses:misc++   The calculated amount depends on the account's balance in the+commodity at that point (which depends on the previously-dated postings+of the commodity to that account since the last balance assertion or+assignment).++   Downsides: using balance assignments makes your journal less+explicit; to know the exact amount posted, you have to run hledger or do+the calculations yourself, instead of just reading it.  Also balance+assignments' forcing of balances can hide errors.  These things make+your financial data less portable, less future-proof, and less+trustworthy in an audit.++* Menu:++* Balance assignments and prices::+* Balance assignments and multiple files::+++File: hledger.info,  Node: Balance assignments and prices,  Next: Balance assignments and multiple files,  Up: Balance assignments++9.28.1.1 Balance assignments and prices+.......................................++A cost in a balance assignment will cause the calculated amount to have+that price attached:++2019/1/1+  (a)             = $1 @ €2++$ hledger print --explicit+2019-01-01+    (a)         $1 @ €2 = $1 @ €2+++File: hledger.info,  Node: Balance assignments and multiple files,  Prev: Balance assignments and prices,  Up: Balance assignments++9.28.1.2 Balance assignments and multiple files+...............................................++Balance assignments handle multiple files like balance assertions.  They+see balance from other files previously included from the current file,+but not from previous sibling or parent files.+++File: hledger.info,  Node: Bracketed posting dates,  Next: D directive,  Prev: Balance assignments,  Up: Other syntax++9.28.2 Bracketed posting dates+------------------------------++For setting posting dates and secondary posting dates, Ledger's+bracketed date syntax is also supported: '[DATE]', '[DATE=DATE2]' or+'[=DATE2]' in posting comments.  hledger will attempt to parse any+square-bracketed sequence of the '0123456789/-.=' characters in this+way.  With this syntax, DATE infers its year from the transaction and+DATE2 infers its year from DATE.++   Downsides: another syntax to learn, redundant with hledger's+'date:'/'date2:' tags, and confusingly similar to Ledger's lot date+syntax.+++File: hledger.info,  Node: D directive,  Next: apply account directive,  Prev: Bracketed posting dates,  Up: Other syntax++9.28.3 'D' directive+--------------------++'D AMOUNT'++   This directive sets a default commodity, to be used for any+subsequent commodityless amounts (ie, plain numbers) seen while parsing+the journal.  This effect lasts until the next 'D' directive, or the end+of the journal.++   For compatibility/historical reasons, 'D' also acts like a+'commodity' directive (setting the commodity's decimal mark for parsing+and display style for output).  So its argument is not just a commodity+symbol, but a full amount demonstrating the style.  The amount must+include a decimal mark (either period or comma).  Eg:++; commodity-less amounts should be treated as dollars+; (and displayed with the dollar sign on the left, thousands separators and two decimal places)+D $1,000.00++1/1+  a     5  ; <- commodity-less amount, parsed as $5 and displayed as $5.00+  b++   Interactions with other directives:++   For setting a commodity's display style, a 'commodity' directive has+highest priority, then a 'D' directive.++   For detecting a commodity's decimal mark during parsing,+'decimal-mark' has highest priority, then 'commodity', then 'D'.++   For checking commodity symbols with the check command, a 'commodity'+directive is required ('hledger check commodities' ignores 'D'+directives).++   Downsides: omitting commodity symbols makes your financial data less+explicit, less portable, and less trustworthy in an audit.  It is+usually an unsustainable shortcut; sooner or later you will want to+track multiple commodities.  D is overloaded with functions redundant+with 'commodity' and 'decimal-mark'.  And it works differently from+Ledger's 'D'.+++File: hledger.info,  Node: apply account directive,  Next: Y directive,  Prev: D directive,  Up: Other syntax++9.28.4 'apply account' directive+--------------------------------++This directive sets a default parent account, which will be prepended to+all accounts in following entries, until an 'end apply account'+directive or end of current file.  Eg:++apply account home++2010/1/1+    food    $10+    cash++end apply account++   is equivalent to:++2010/01/01+    home:food           $10+    home:cash          $-10++   'account' directives are also affected, and so is any 'include'd+content.++   Account names entered via hledger add or hledger-web are not+affected.++   Account aliases, if any, are applied after the parent account is+prepended.++   Downsides: this can make your financial data less explicit, less+portable, and less trustworthy in an audit.+++File: hledger.info,  Node: Y directive,  Next: Secondary dates,  Prev: apply account directive,  Up: Other syntax++9.28.5 'Y' directive+--------------------++'Y YEAR'++   or (deprecated backward-compatible forms):++   'year YEAR' 'apply year YEAR'++   The space is optional.  This sets a default year to be used for+subsequent dates which don't specify a year.  Eg:++Y2009  ; set default year to 2009++12/15  ; equivalent to 2009/12/15+  expenses  1+  assets++year 2010  ; change default year to 2010++2009/1/30  ; specifies the year, not affected+  expenses  1+  assets++1/31   ; equivalent to 2010/1/31+  expenses  1+  assets++   Downsides: omitting the year (from primary transaction dates, at+least) makes your financial data less explicit, less portable, and less+trustworthy in an audit.  Such dates can get separated from their+corresponding Y directive, eg when evaluating a region of the journal in+your editor.  A missing Y directive makes reports dependent on today's+date.+++File: hledger.info,  Node: Secondary dates,  Next: Star comments,  Prev: Y directive,  Up: Other syntax++9.28.6 Secondary dates+----------------------++A secondary date is written after the primary date, following an equals+sign.  If the year is omitted, the primary date's year is assumed.  When+running reports, the primary (left) date is used by default, but with+the '--date2' flag (or '--aux-date' or '--effective'), the secondary+(right) date will be used instead.++   The meaning of secondary dates is up to you, but it's best to follow+a consistent rule.  Eg "primary = the bank's clearing date, secondary =+date the transaction was initiated, if different".++   Downsides: makes your financial data more complicated, less portable,+and less trustworthy in an audit.  Keeping the meaning of the two dates+consistent requires discipline, and you have to remember which reporting+mode is appropriate for a given report.  Posting dates are simpler and+better.+++File: hledger.info,  Node: Star comments,  Next: Valuation expressions,  Prev: Secondary dates,  Up: Other syntax++9.28.7 Star comments+--------------------++Lines beginning with '*' (star/asterisk) are also comment lines.  This+feature allows Emacs users to insert org headings in their journal,+allowing them to fold/unfold/navigate it like an outline when viewed+with org mode.++   Downsides: another, unconventional comment syntax to learn.+Decreases your journal's portability.  And switching to Emacs org mode+just for folding/unfolding meant losing the benefits of ledger mode;+nowadays you can add outshine mode to ledger mode to get folding without+losing ledger mode's features.+++File: hledger.info,  Node: Valuation expressions,  Next: Virtual postings,  Prev: Star comments,  Up: Other syntax++9.28.8 Valuation expressions+----------------------------++Ledger allows a valuation function or value to be written in double+parentheses after an amount.  hledger ignores these.+++File: hledger.info,  Node: Virtual postings,  Next: Other Ledger directives,  Prev: Valuation expressions,  Up: Other syntax++9.28.9 Virtual postings+-----------------------++A posting with parentheses around the account name ('(some:account)') is+called a _unbalanced virtual posting_.  Such postings do not participate+in transaction balancing.  (And if you write them without an amount, a+zero amount is always inferred.)  These can occasionally be convenient+for special circumstances, but they violate double entry bookkeeping and+make your data less portable across applications, so many people avoid+using them at all.++   A posting with brackets around the account name ('[some:account]') is+called a _balanced virtual posting_.  The balanced virtual postings in a+transaction must add up to zero, just like ordinary postings, but+separately from them.  These are not part of double entry bookkeeping+either, but they are at least balanced.  An example:++2022-01-01 buy food with cash, update budget envelope subaccounts, & something else+  assets:cash                    $-10  ; <- these balance each other+  expenses:food                    $7  ; <-+  expenses:food                    $3  ; <-+  [assets:checking:budget:food]  $-10  ;   <- and these balance each other+  [assets:checking:available]     $10  ;   <-+  (something:else)                 $5  ;     <- this is not required to balance++   Ordinary postings, whose account names are neither parenthesised nor+bracketed, are called _real postings_.  You can exclude virtual postings+from reports with the '-R/--real' flag or a 'real:1' query.+++File: hledger.info,  Node: Other Ledger directives,  Prev: Virtual postings,  Up: Other syntax++9.28.10 Other Ledger directives+-------------------------------++These other Ledger directives are currently accepted but ignored.  This+allows hledger to read more Ledger files, but be aware that hledger's+reports may differ from Ledger's if you use these.++apply fixed COMM AMT+apply tag   TAG+assert      EXPR+bucket / A  ACCT+capture     ACCT REGEX+check       EXPR+define      VAR=EXPR+end apply fixed+end apply tag+end apply year+end tag+eval / expr EXPR+python+  PYTHONCODE+tag         NAME+value       EXPR+--command-line-flags++   See also https://hledger.org/ledger.html for a detailed+hledger/Ledger syntax comparison.+++File: hledger.info,  Node: CSV,  Next: Timeclock,  Prev: Journal,  Up: Top++10 CSV+******++hledger can read CSV files (Character Separated Value - usually comma,+semicolon, or tab) containing dated records, automatically converting+each record into a transaction.++   (To learn about _writing_ CSV, see CSV output.)++   For best error messages when reading CSV/TSV/SSV files, make sure+they have a corresponding '.csv', '.tsv' or '.ssv' file extension or use+a hledger file prefix (see File Extension below).++   Each CSV file must be described by a corresponding _rules file_.+This contains rules describing the CSV data (header line, fields layout,+date format etc.), how to construct hledger transactions from it, and+how to categorise transactions based on description or other attributes.++   By default hledger looks for a rules file named like the CSV file+with an extra '.rules' extension, in the same directory.  Eg when asked+to read 'foo/FILE.csv', hledger looks for 'foo/FILE.csv.rules'.  You can+specify a different rules file with the '--rules-file' option.  If no+rules file is found, hledger will create a sample rules file, which+you'll need to adjust.++   At minimum, the rules file must identify the date and amount fields,+and often it also specifies the date format and how many header lines+there are.  Here's a simple CSV file and a rules file for it:++Date, Description, Id, Amount+12/11/2019, Foo, 123, 10.23++# basic.csv.rules+skip         1+fields       date, description, , amount+date-format  %d/%m/%Y++$ hledger print -f basic.csv+2019-11-12 Foo+    expenses:unknown           10.23+    income:unknown            -10.23++   There's an introductory Importing CSV data tutorial on hledger.org,+and more CSV rules examples below, and a larger collection at+https://github.com/simonmichael/hledger/tree/master/examples/csv.++* Menu:++* CSV rules cheatsheet::+* source::+* separator::+* skip::+* date-format::+* timezone::+* newest-first::+* intra-day-reversed::+* decimal-mark::+* fields list::+* Field assignment::+* Field names::+* if block::+* Matchers::+* if table::+* balance-type::+* include::+* Working with CSV::+* CSV rules examples::+++File: hledger.info,  Node: CSV rules cheatsheet,  Next: source,  Up: CSV++10.1 CSV rules cheatsheet+=========================++The following kinds of rule can appear in the rules file, in any order.+(Blank lines and lines beginning with '#' or ';' or '*' are ignored.)++*'source'*               optionally declare which file to read data+                         from+*'separator'*            declare the field separator, instead of+                         relying on file extension+*'skip'*                 skip one or more header lines at start of file+*'date-format'*          declare how to parse CSV dates/date-times+*'timezone'*             declare the time zone of ambiguous CSV+                         date-times+*'newest-first'*         improve txn order when: there are multiple+                         records, newest first, all with the same date+*'intra-day-reversed'*   improve txn order when: same-day txns are in+                         opposite order to the overall file+*'decimal-mark'*         declare the decimal mark used in CSV amounts,+                         when ambiguous+*'fields' list*          name CSV fields for easy reference, and+                         optionally assign their values to hledger+                         fields+*Field assignment*       assign a CSV value or interpolated text value+                         to a hledger field+*'if' block*             conditionally assign values to hledger fields,+                         or 'skip' a record or 'end' (skip rest of+                         file)+*'if' table*             conditionally assign values to hledger fields,+                         using compact syntax+*'balance-type'*         select which type of balance+                         assertions/assignments to generate+*'include'*              inline another CSV rules file++   Working with CSV tips can be found below, including How CSV rules are+evaluated.+++File: hledger.info,  Node: source,  Next: separator,  Prev: CSV rules cheatsheet,  Up: CSV++10.2 'source'+=============++If you tell hledger to read a csv file with '-f foo.csv', it will look+for rules in 'foo.csv.rules'.  Or, you can tell it to read the rules+file, with '-f foo.csv.rules', and it will look for data in 'foo.csv'+(since 1.30).++   These are mostly equivalent, but the second method provides some+extra features.  For one, the data file can be missing, without causing+an error; it is just considered empty.  And, you can specify a different+data file by adding a "source" rule:++source ./Checking1.csv++   If you specify just a file name with no path, hledger will look for+it in your system's downloads directory ('~/Downloads', currently):++source Checking1.csv++   And if you specify a glob pattern, hledger will read the most recent+of the matched files (useful with repeated downloads):++source Checking1*.csv++   See also "Working with CSV > Reading files specified by rule".+++File: hledger.info,  Node: separator,  Next: skip,  Prev: source,  Up: CSV++10.3 'separator'+================++You can use the 'separator' rule to read other kinds of+character-separated data.  The argument is any single separator+character, or the words 'tab' or 'space' (case insensitive).  Eg, for+comma-separated values (CSV):++separator ,++   or for semicolon-separated values (SSV):++separator ;++   or for tab-separated values (TSV):++separator TAB++   If the input file has a '.csv', '.ssv' or '.tsv' file extension (or a+'csv:', 'ssv:', 'tsv:' prefix), the appropriate separator will be+inferred automatically, and you won't need this rule.+++File: hledger.info,  Node: skip,  Next: date-format,  Prev: separator,  Up: CSV++10.4 'skip'+===========++skip N++   The word 'skip' followed by a number (or no number, meaning 1) tells+hledger to ignore this many non-empty lines at the start of the input+data.  You'll need this whenever your CSV data contains header lines.+Note, empty and blank lines are skipped automatically, so you don't need+to count those.++   'skip' has a second meaning: it can be used inside if blocks+(described below), to skip one or more records whenever the condition is+true.  Records skipped in this way are ignored, except they are still+required to be valid CSV.+++File: hledger.info,  Node: date-format,  Next: timezone,  Prev: skip,  Up: CSV++10.5 'date-format'+==================++date-format DATEFMT++   This is a helper for the 'date' (and 'date2') fields.  If your CSV+dates are not formatted like 'YYYY-MM-DD', 'YYYY/MM/DD' or 'YYYY.MM.DD',+you'll need to add a date-format rule describing them with a+strptime-style date parsing pattern - see+https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime.+The pattern must parse the CSV date value completely.  Some examples:++# MM/DD/YY+date-format %m/%d/%y++# D/M/YYYY+# The - makes leading zeros optional.+date-format %-d/%-m/%Y++# YYYY-Mmm-DD+date-format %Y-%h-%d++# M/D/YYYY HH:MM AM some other junk+# Note the time and junk must be fully parsed, though only the date is used.+date-format %-m/%-d/%Y %l:%M %p some other junk+++File: hledger.info,  Node: timezone,  Next: newest-first,  Prev: date-format,  Up: CSV++10.6 'timezone'+===============++timezone TIMEZONE++   When CSV contains date-times that are implicitly in some time zone+other than yours, but containing no explicit time zone information, you+can use this rule to declare the CSV's native time zone, which helps+prevent off-by-one dates.++   When the CSV date-times do contain time zone information, you don't+need this rule; instead, use '%Z' in 'date-format' (or '%z', '%EZ',+'%Ez'; see the formatTime link above).++   In either of these cases, hledger will do a time-zone-aware+conversion, localising the CSV date-times to your current system time+zone.  If you prefer to localise to some other time zone, eg for+reproducibility, you can (on unix at least) set the output timezone with+the TZ environment variable, eg:++$ TZ=-1000 hledger print -f foo.csv  # or TZ=-1000 hledger import foo.csv++   'timezone' currently does not understand timezone names, except+"UTC", "GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT".+For others, use numeric format: +HHMM or -HHMM.+++File: hledger.info,  Node: newest-first,  Next: intra-day-reversed,  Prev: timezone,  Up: CSV++10.7 'newest-first'+===================++hledger tries to ensure that the generated transactions will be ordered+chronologically, including same-day transactions.  Usually it can+auto-detect how the CSV records are ordered.  But if it encounters CSV+where all records are on the same date, it assumes that the records are+oldest first.  If in fact the CSV's records are normally newest first,+like:++2022-10-01, txn 3...+2022-10-01, txn 2...+2022-10-01, txn 1...++   you can add the 'newest-first' rule to help hledger generate the+transactions in correct order.++# same-day CSV records are newest first+newest-first+++File: hledger.info,  Node: intra-day-reversed,  Next: decimal-mark,  Prev: newest-first,  Up: CSV++10.8 'intra-day-reversed'+=========================++If CSV records within a single day are ordered opposite to the overall+record order, you can add the 'intra-day-reversed' rule to improve the+order of journal entries.  Eg, here the overall record order is newest+first, but same-day records are oldest first:++2022-10-02, txn 3...+2022-10-02, txn 4...+2022-10-01, txn 1...+2022-10-01, txn 2...++# transactions within each day are reversed with respect to the overall date order+intra-day-reversed+++File: hledger.info,  Node: decimal-mark,  Next: fields list,  Prev: intra-day-reversed,  Up: CSV++10.9 'decimal-mark'+===================++decimal-mark .++   or:++decimal-mark ,++   hledger automatically accepts either period or comma as a decimal+mark when parsing numbers (cf Amounts).  However if any numbers in the+CSV contain digit group marks, such as thousand-separating commas, you+should declare the decimal mark explicitly with this rule, to avoid+misparsed numbers.+++File: hledger.info,  Node: fields list,  Next: Field assignment,  Prev: decimal-mark,  Up: CSV++10.10 'fields' list+===================++fields FIELDNAME1, FIELDNAME2, ...++   A fields list (the word 'fields' followed by comma-separated field+names) is optional, but convenient.  It does two things:++  1. It names the CSV field in each column.  This can be convenient if+     you are referencing them in other rules, so you can say+     '%SomeField' instead of remembering '%13'.++  2. Whenever you use one of the special hledger field names (described+     below), it assigns the CSV value in this position to that hledger+     field.  This is the quickest way to populate hledger's fields and+     build a transaction.++   Here's an example that says "use the 1st, 2nd and 4th fields as the+transaction's date, description and amount; name the last two fields for+later reference; and ignore the others":++fields date, description, , amount, , , somefield, anotherfield++   In a fields list, the separator is always comma; it is unrelated to+the CSV file's separator.  Also:++   * There must be least two items in the list (at least one comma).+   * Field names may not contain spaces.  Spaces before/after field+     names are optional.+   * Field names may contain '_' (underscore) or '-' (hyphen).+   * Fields you don't care about can be given a dummy name or an empty+     name.++   If the CSV contains column headings, it's convenient to use these for+your field names, suitably modified (eg lower-cased with spaces replaced+by underscores).++   Sometimes you may want to alter a CSV field name to avoid assigning+to a hledger field with the same name.  Eg you could call the CSV's+"balance" field 'balance_' to avoid directly setting hledger's 'balance'+field (and generating a balance assertion).+++File: hledger.info,  Node: Field assignment,  Next: Field names,  Prev: fields list,  Up: CSV++10.11 Field assignment+======================++HLEDGERFIELD FIELDVALUE++   Field assignments are the more flexible way to assign CSV values to+hledger fields.  They can be used instead of or in addition to a fields+list (see above).++   To assign a value to a hledger field, write the field name (any of+the standard hledger field/pseudo-field names, defined below), a space,+followed by a text value on the same line.  This text value may+interpolate CSV fields, referenced either by their 1-based position in+the CSV record ('%N') or by the name they were given in the fields list+('%CSVFIELD'), and regular expression match groups ('\N').++   Some examples:++# set the amount to the 4th CSV field, with " USD" appended+amount %4 USD++# combine three fields to make a comment, containing note: and date: tags+comment note: %somefield - %anotherfield, date: %1++   Tips:++   * Interpolation strips outer whitespace (so a CSV value like '" 1 "'+     becomes '1' when interpolated) (#1051).+   * Interpolations always refer to a CSV field - you can't interpolate+     a hledger field.  (See Referencing other fields below).+++File: hledger.info,  Node: Field names,  Next: if block,  Prev: Field assignment,  Up: CSV++10.12 Field names+=================++Note the two kinds of field names mentioned here, and used only in+hledger CSV rules files:++  1. *CSV field names* ('CSVFIELD' in these docs): you can optionally+     name the CSV columns for easy reference (since hledger doesn't yet+     automatically recognise column headings in a CSV file), by writing+     arbitrary names in a 'fields' list, eg:++     fields When, What, Some_Id, Net, Total, Foo, Bar++  2. Special *hledger field names* ('HLEDGERFIELD' in these docs): you+     must set at least some of these to generate the hledger transaction+     from a CSV record, by writing them as the left hand side of a field+     assignment, eg:++     date        %When+     code        %Some_Id+     description %What+     comment     %Foo %Bar+     amount1     $ %Total++     or directly in a 'fields' list:++     fields date, description, code, , amount1, Foo, Bar+     currency $+     comment  %Foo %Bar++   Here are all the special hledger field names available, and what+happens when you assign values to them:++* Menu:++* date field::+* date2 field::+* status field::+* code field::+* description field::+* comment field::+* account field::+* amount field::+* currency field::+* balance field::+++File: hledger.info,  Node: date field,  Next: date2 field,  Up: Field names++10.12.1 date field+------------------++Assigning to 'date' sets the transaction date.+++File: hledger.info,  Node: date2 field,  Next: status field,  Prev: date field,  Up: Field names++10.12.2 date2 field+-------------------++'date2' sets the transaction's secondary date, if any.+++File: hledger.info,  Node: status field,  Next: code field,  Prev: date2 field,  Up: Field names++10.12.3 status field+--------------------++'status' sets the transaction's status, if any.+++File: hledger.info,  Node: code field,  Next: description field,  Prev: status field,  Up: Field names++10.12.4 code field+------------------++'code' sets the transaction's code, if any.+++File: hledger.info,  Node: description field,  Next: comment field,  Prev: code field,  Up: Field names++10.12.5 description field+-------------------------++'description' sets the transaction's description, if any.+++File: hledger.info,  Node: comment field,  Next: account field,  Prev: description field,  Up: Field names++10.12.6 comment field+---------------------++'comment' sets the transaction's comment, if any.++   'commentN', where N is a number, sets the Nth posting's comment.++   You can assign multi-line comments by writing literal '\n' in the+code.  A comment starting with '\n' will begin on a new line.++   Comments can contain tags, as usual.+++File: hledger.info,  Node: account field,  Next: amount field,  Prev: comment field,  Up: Field names++10.12.7 account field+---------------------++Assigning to 'accountN', where N is 1 to 99, sets the account name of+the Nth posting, and causes that posting to be generated.++   Most often there are two postings, so you'll want to set 'account1'+and 'account2'.  Typically 'account1' is associated with the CSV file,+and is set once with a top-level assignment, while 'account2' is set+based on each transaction's description, in conditional rules.++   If a posting's account name is left unset but its amount is set (see+below), a default account name will be chosen (like "expenses:unknown"+or "income:unknown").+++File: hledger.info,  Node: amount field,  Next: currency field,  Prev: account field,  Up: Field names++10.12.8 amount field+--------------------++There are several ways to set posting amounts from CSV, useful in+different situations.++  1. *'amount'* is the oldest and simplest.  Assigning to this sets the+     amount of the first and second postings.  In the second posting,+     the amount will be negated; also, if it has a cost attached, it+     will be converted to cost.++  2. *'amount-in'* and *'amount-out'* work exactly like the above, but+     should be used when the CSV has two amount fields (such as "Debit"+     and "Credit", or "Inflow" and "Outflow").  Whichever field has a+     non-zero value will be used as the amount of the first and second+     postings.  Here are some tips to avoid confusion:++        * It's not "amount-in for posting 1 and amount-out for posting+          2", it is "extract a single amount from the amount-in or+          amount-out field, and use that for posting 1 and (negated) for+          posting 2".+        * Don't use both 'amount' and 'amount-in'/'amount-out' in the+          same rules file; choose based on whether the amount is in a+          single CSV field or spread across two fields.+        * In each record, at most one of the two CSV fields should+          contain a non-zero amount; the other field must contain a zero+          or nothing.+        * hledger assumes both CSV fields contain unsigned numbers, and+          it automatically negates the amount-out values.+        * If the data doesn't fit these requirements, you'll probably+          need an if rule (see below).++  3. *'amountN'* (where N is a number from 1 to 99) sets the amount of+     only a single posting: the Nth posting in the transaction.  You'll+     usually need at least two such assignments to make a balanced+     transaction.  You can also generate more than two postings, to+     represent more complex transactions.  The posting numbers don't+     have to be consecutive; with if rules, higher posting numbers can+     be useful to ensure a certain order of postings.++  4. *'amountN-in'* and *'amountN-out'* work exactly like the above, but+     should be used when the CSV has two amount fields.  This is+     analogous to 'amount-in' and 'amount-out', and those tips also+     apply here.++  5. Remember that a 'fields' list can also do assignments.  So in a+     fields list if you name a CSV field "amount", that counts as+     assigning to 'amount'.  (If you don't want that, call it something+     else in the fields list, like "amount_".)++  6. The above don't handle every situation; if you need more+     flexibility, use an 'if' rule to set amounts conditionally.  See+     "Working with CSV > Setting amounts" below for more on this and on+     amount-setting generally.+++File: hledger.info,  Node: currency field,  Next: balance field,  Prev: amount field,  Up: Field names++10.12.9 currency field+----------------------++'currency' sets a currency symbol, to be prepended to all postings'+amounts.  You can use this if the CSV amounts do not have a currency+symbol, eg if it is in a separate column.++   'currencyN' prepends a currency symbol to just the Nth posting's+amount.+++File: hledger.info,  Node: balance field,  Prev: currency field,  Up: Field names++10.12.10 balance field+----------------------++'balanceN' sets a balance assertion amount (or if the posting amount is+left empty, a balance assignment) on posting N.++   'balance' is a compatibility spelling for hledger <1.17; it is+equivalent to 'balance1'.++   You can adjust the type of assertion/assignment with the+'balance-type' rule (see below).++   See Tips below for more about setting amounts and currency.+++File: hledger.info,  Node: if block,  Next: Matchers,  Prev: Field names,  Up: CSV++10.13 'if' block+================++Rules can be applied conditionally, depending on patterns in the CSV+data.  This allows flexibility; in particular, it is how you can+categorise transactions, selecting an appropriate account name based on+their description (for example).  There are two ways to write+conditional rules: "if blocks", described here, and "if tables",+described below.++   An if block is the word 'if' and one or more "matcher" expressions+(can be a word or phrase), one per line, starting either on the same or+next line; followed by one or more indented rules.  Eg,++if MATCHER+ RULE++   or++if+MATCHER+MATCHER+MATCHER+ RULE+ RULE++   If any of the matchers succeeds, all of the indented rules will be+applied.  They are usually field assignments, but the following special+rules may also be used within an if block:++   * 'skip' - skips the matched CSV record (generating no transaction+     from it)+   * 'end' - skips the rest of the current CSV file.++   Some examples:++# if the record contains "groceries", set account2 to "expenses:groceries"+if groceries+ account2 expenses:groceries++# if the record contains any of these phrases, set account2 and a transaction comment as shown+if+monthly service fee+atm transaction fee+banking thru software+ account2 expenses:business:banking+ comment  XXX deductible ? check it++# if an empty record is seen (assuming five fields), ignore the rest of the CSV file+if ,,,,+ end+++File: hledger.info,  Node: Matchers,  Next: if table,  Prev: if block,  Up: CSV++10.14 Matchers+==============++There are two kinds:++  1. A record matcher is a word or single-line text fragment or regular+     expression ('REGEX'), which hledger will try to match+     case-insensitively anywhere within the CSV record.+     Eg: 'whole foods'++  2. A field matcher is preceded with a percent sign and CSV field name+     ('%CSVFIELD REGEX').  hledger will try to match these just within+     the named CSV field.+     Eg: '%date 2023'++   The regular expression is (as usual in hledger) a POSIX extended+regular expression, that also supports GNU word boundaries ('\b', '\B',+'\<', '\>'), and nothing else.  If you have trouble, see "Regular+expressions" in the hledger manual+(https://hledger.org/hledger.html#regular-expressions).++* Menu:++* What matchers match::+* Combining matchers::+* Match groups::+++File: hledger.info,  Node: What matchers match,  Next: Combining matchers,  Up: Matchers++10.14.1 What matchers match+---------------------------++With record matchers, it's important to know that the record matched is+not the original CSV record, but a modified one: separators will be+converted to commas, and enclosing double quotes (but not enclosing+whitespace) are removed.  So for example, when reading an SSV file, if+the original record was:++2023-01-01; "Acme, Inc.";  1,000++   the regex would see, and try to match, this modified record text:++2023-01-01,Acme, Inc.,  1,000+++File: hledger.info,  Node: Combining matchers,  Next: Match groups,  Prev: What matchers match,  Up: Matchers++10.14.2 Combining matchers+--------------------------++When an if block has multiple matchers, they are combined as follows:++   * By default they are OR'd (any one of them can match)+   * When a matcher is preceded by ampersand ('&') it will be AND'ed+     with the previous matcher (both of them must match)+   * When a matcher is preceded by an exclamation mark ('!'), the+     matcher is negated (it may not match).++   Currently there is a limitation: you can't use both '&' and '!' on+the same line (you can't AND a negated matcher).+++File: hledger.info,  Node: Match groups,  Prev: Combining matchers,  Up: Matchers++10.14.3 Match groups+--------------------++Matchers can define match groups: parenthesised portions of the regular+expression which are available for reference in field assignments.+Groups are enclosed in regular parentheses ('(' and ')') and can be+nested.  Each group is available in field assignments using the token+'\N', where N is an index into the match groups for this conditional+block (e.g.  '\1', '\2', etc.).++   Example: Warp credit card payment postings to the beginning of the+billing period (Month start), to match how they are presented in+statements, using posting dates:++if %date (....-..)-..+  comment2 date:\1-01++   Another example: Read the expense account from the CSV field, but+throw away a prefix:++if %account1 liabilities:family:(expenses:.*)+    account1 \1+++File: hledger.info,  Node: if table,  Next: balance-type,  Prev: Matchers,  Up: CSV++10.15 'if' table+================++"if tables" are an alternative to if blocks; they can express many+matchers and field assignments in a more compact tabular format, like+this:++if,HLEDGERFIELD1,HLEDGERFIELD2,...+MATCHERA,VALUE1,VALUE2,...+MATCHERB,VALUE1,VALUE2,...+MATCHERC,VALUE1,VALUE2,...+<empty line>++   The first character after 'if' is taken to be this if table's field+separator.  It is unrelated to the separator used in the CSV file.  It+should be a non-alphanumeric character like ',' or '|' that does not+appear anywhere else in the table (it should not be used in field names+or matchers or values, and it cannot be escaped with a backslash).++   Each line must contain the same number of separators; empty values+are allowed.  Whitespace can be used in the matcher lines for+readability (but not in the if line, currently).  The table must be+terminated by an empty line (or end of file).++   An if table like the above is interpreted as follows: try all of the+matchers; whenever a matcher succeeds, assign all of the values on that+line to the corresponding hledger fields; later lines can overrider+earlier ones.  It is equivalent to this sequence of if blocks:++if MATCHERA+  HLEDGERFIELD1 VALUE1+  HLEDGERFIELD2 VALUE2+  ...++if MATCHERB+  HLEDGERFIELD1 VALUE1+  HLEDGERFIELD2 VALUE2+  ...++if MATCHERC+  HLEDGERFIELD1 VALUE1+  HLEDGERFIELD2 VALUE2+  ...++   Example:++if,account2,comment+atm transaction fee,expenses:business:banking,deductible? check it+%description groceries,expenses:groceries,+2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out+++File: hledger.info,  Node: balance-type,  Next: include,  Prev: if table,  Up: CSV++10.16 'balance-type'+====================++Balance assertions generated by assigning to balanceN are of the simple+'=' type by default, which is a single-commodity, subaccount-excluding+assertion.  You may find the subaccount-including variants more useful,+eg if you have created some virtual subaccounts of checking to help with+budgeting.  You can select a different type of assertion with the+'balance-type' rule:++# balance assertions will consider all commodities and all subaccounts+balance-type ==*++   Here are the balance assertion types for quick reference:++=    single commodity, exclude subaccounts+=*   single commodity, include subaccounts+==   multi commodity,  exclude subaccounts+==*  multi commodity,  include subaccounts+++File: hledger.info,  Node: include,  Next: Working with CSV,  Prev: balance-type,  Up: CSV++10.17 'include'+===============++include RULESFILE++   This includes the contents of another CSV rules file at this point.+'RULESFILE' is an absolute file path or a path relative to the current+file's directory.  This can be useful for sharing common rules between+several rules files, eg:++# someaccount.csv.rules++## someaccount-specific rules+fields   date,description,amount+account1 assets:someaccount+account2 expenses:misc++## common rules+include categorisation.rules+++File: hledger.info,  Node: Working with CSV,  Next: CSV rules examples,  Prev: include,  Up: CSV++10.18 Working with CSV+======================++Some tips:++* Menu:++* Rapid feedback::+* Valid CSV::+* File Extension::+* Reading CSV from standard input::+* Reading multiple CSV files::+* Reading files specified by rule::+* Valid transactions::+* Deduplicating importing::+* Setting amounts::+* Amount signs::+* Setting currency/commodity::+* Amount decimal places::+* Referencing other fields::+* How CSV rules are evaluated::+* Well factored rules::+++File: hledger.info,  Node: Rapid feedback,  Next: Valid CSV,  Up: Working with CSV++10.18.1 Rapid feedback+----------------------++It's a good idea to get rapid feedback while creating/troubleshooting+CSV rules.  Here's a good way, using entr from eradman.com/entrproject:++$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC'++   A desc: query (eg) is used to select just one, or a few, transactions+of interest.  "bash -c" is used to run multiple commands, so we can echo+a separator each time the command re-runs, making it easier to read the+output.+++File: hledger.info,  Node: Valid CSV,  Next: File Extension,  Prev: Rapid feedback,  Up: Working with CSV++10.18.2 Valid CSV+-----------------++Note that hledger will only accept valid CSV conforming to RFC 4180, and+equivalent SSV and TSV formats (like RFC 4180 but with semicolon or tab+as separators).  This means, eg:++   * Values may be enclosed in double quotes, or not.  Enclosing in+     single quotes is not allowed.  (Eg ''A','B'' is rejected.)+   * When values are enclosed in double quotes, spaces outside the+     quotes are not allowed.  (Eg '"A", "B"' is rejected.)+   * When values are not enclosed in quotes, they may not contain double+     quotes.  (Eg 'A"A, B' is rejected.)++   If your CSV/SSV/TSV is not valid in this sense, you'll need to+transform it before reading with hledger.  Try using sed, or a more+permissive CSV parser like python's csv lib.+++File: hledger.info,  Node: File Extension,  Next: Reading CSV from standard input,  Prev: Valid CSV,  Up: Working with CSV++10.18.3 File Extension+----------------------++To help hledger choose the CSV file reader and show the right error+messages (and choose the right field separator character by default),+it's best if CSV/SSV/TSV files are named with a '.csv', '.ssv' or '.tsv'+filename extension.  (More about this at Data formats.)++   When reading files with the "wrong" extension, you can ensure the CSV+reader (and the default field separator) by prefixing the file path with+'csv:', 'ssv:' or 'tsv:': Eg:++$ hledger -f ssv:foo.dat print++   You can also override the default field separator with a separator+rule if needed.+++File: hledger.info,  Node: Reading CSV from standard input,  Next: Reading multiple CSV files,  Prev: File Extension,  Up: Working with CSV++10.18.4 Reading CSV from standard input+---------------------------------------++You'll need the file format prefix when reading CSV from stdin also,+since hledger assumes journal format by default.  Eg:++$ cat foo.dat | hledger -f ssv:- print+++File: hledger.info,  Node: Reading multiple CSV files,  Next: Reading files specified by rule,  Prev: Reading CSV from standard input,  Up: Working with CSV++10.18.5 Reading multiple CSV files+----------------------------------++If you use multiple '-f' options to read multiple CSV files at once,+hledger will look for a correspondingly-named rules file for each CSV+file.  But if you use the '--rules-file' option, that rules file will be+used for all the CSV files.+++File: hledger.info,  Node: Reading files specified by rule,  Next: Valid transactions,  Prev: Reading multiple CSV files,  Up: Working with CSV++10.18.6 Reading files specified by rule+---------------------------------------++Instead of specifying a CSV file in the command line, you can specify a+rules file, as in 'hledger -f foo.csv.rules CMD'.  By default this will+read data from foo.csv in the same directory, but you can add a source+rule to specify a different data file, perhaps located in your web+browser's download directory.++   This feature was added in hledger 1.30, so you won't see it in most+CSV rules examples.  But it helps remove some of the busywork of+managing CSV downloads.  Most of your financial institutions's default+CSV filenames are different and can be recognised by a glob pattern.  So+you can put a rule like 'source Checking1*.csv' in+foo-checking.csv.rules, and then periodically follow a workflow like:++  1. Download CSV from Foo's website, using your browser's defaults+  2. Run 'hledger import foo-checking.csv.rules' to import any new+     transactions++   After import, you can: discard the CSV, or leave it where it is for a+while, or move it into your archives, as you prefer.  If you do nothing,+next time your browser will save something like Checking1-2.csv, and+hledger will use that because of the '*' wild card and because it is the+most recent.+++File: hledger.info,  Node: Valid transactions,  Next: Deduplicating importing,  Prev: Reading files specified by rule,  Up: Working with CSV++10.18.7 Valid transactions+--------------------------++After reading a CSV file, hledger post-processes and validates the+generated journal entries as it would for a journal file - balancing+them, applying balance assignments, and canonicalising amount styles.+Any errors at this stage will be reported in the usual way, displaying+the problem entry.++   There is one exception: balance assertions, if you have generated+them, will not be checked, since normally these will work only when the+CSV data is part of the main journal.  If you do need to check balance+assertions generated from CSV right away, pipe into another hledger:++$ hledger -f file.csv print | hledger -f- print+++File: hledger.info,  Node: Deduplicating importing,  Next: Setting amounts,  Prev: Valid transactions,  Up: Working with CSV++10.18.8 Deduplicating, importing+--------------------------------++When you download a CSV file periodically, eg to get your latest bank+transactions, the new file may overlap with the old one, containing some+of the same records.++   The import command will (a) detect the new transactions, and (b)+append just those transactions to your main journal.  It is idempotent,+so you don't have to remember how many times you ran it or with which+version of the CSV. (It keeps state in a hidden '.latest.FILE.csv'+file.)  This is the easiest way to import CSV data.  Eg:++# download the latest CSV files, then run this command.+# Note, no -f flags needed here.+$ hledger import *.csv [--dry]++   This method works for most CSV files.  (Where records have a stable+chronological order, and new records appear only at the new end.)++   A number of other tools and workflows, hledger-specific and+otherwise, exist for converting, deduplicating, classifying and managing+CSV data.  See:++   * https://hledger.org/cookbook.html#setups-and-workflows+   * https://plaintextaccounting.org -> data import/conversion+++File: hledger.info,  Node: Setting amounts,  Next: Amount signs,  Prev: Deduplicating importing,  Up: Working with CSV++10.18.9 Setting amounts+-----------------------++Continuing from amount field above, here are more tips for+amount-setting:++  1. *If the amount is in a single CSV field:*++       a. *If its sign indicates direction of flow:*+          Assign it to 'amountN', to set the Nth posting's amount.  N is+          usually 1 or 2 but can go up to 99.++       b. *If another field indicates direction of flow:*+          Use one or more conditional rules to set the appropriate+          amount sign.  Eg:++     # assume a withdrawal unless Type contains "deposit":+     amount1  -%Amount+     if %Type deposit+       amount1  %Amount++  2. *If the amount is in two CSV fields (such as Debit and Credit, or+     In and Out):*++       a. *If both fields are unsigned:*+          Assign one field to 'amountN-in' and the other to+          'amountN-out'.  hledger will automatically negate the "out"+          field, and will use whichever field value is non-zero as+          posting N's amount.++       b. *If either field is signed:*+          You will probably need to override hledger's sign for one or+          the other field, as in the following example:++     # Negate the -out value, but only if it is not empty:+     fields date, description, amount1-in, amount1-out+     if %amount1-out [1-9]+      amount1-out -%amount1-out++       c. *If both fields can contain a non-zero value (or both can be+          empty):*+          The -in/-out rules normally choose the value which is+          non-zero/non-empty.  Some value pairs can be ambiguous, such+          as '1' and 'none'.  For such cases, use conditional rules to+          help select the amount.  Eg, to handle the above you could+          select the value containing non-zero digits:++     fields date, description, in, out+     if %in [1-9]+      amount1 %in+     if %out [1-9]+      amount1 %out++  3. *If you want posting 2's amount converted to cost:*+     Use the unnumbered 'amount' (or 'amount-in' and 'amount-out')+     syntax.++  4. *If the CSV has only balance amounts, not transaction amounts:*+     Assign to 'balanceN', to set a balance assignment on the Nth+     posting, causing the posting's amount to be calculated+     automatically.  'balance' with no number is equivalent to+     'balance1'.  In this situation hledger is more likely to guess the+     wrong default account name, so you may need to set that explicitly.+++File: hledger.info,  Node: Amount signs,  Next: Setting currency/commodity,  Prev: Setting amounts,  Up: Working with CSV++10.18.10 Amount signs+---------------------++There is some special handling making it easier to parse and to reverse+amount signs.  (This only works for whole amounts, not for cost amounts+such as COST in 'amount1 AMT @ COST'):++   * *If an amount value begins with a plus sign:*+     that will be removed: '+AMT' becomes 'AMT'++   * *If an amount value is parenthesised:*+     it will be de-parenthesised and sign-flipped: '(AMT)' becomes+     '-AMT'++   * *If an amount value has two minus signs (or two sets of+     parentheses, or a minus sign and parentheses):*+     they cancel out and will be removed: '--AMT' or '-(AMT)' becomes+     'AMT'++   * *If an amount value contains just a sign (or just a set of+     parentheses):*+     that is removed, making it an empty value.  '"+"' or '"-"' or+     '"()"' becomes '""'.++   It's not possible (without preprocessing the CSV) to set an amount to+its absolute value, ie discard its sign.+++File: hledger.info,  Node: Setting currency/commodity,  Next: Amount decimal places,  Prev: Amount signs,  Up: Working with CSV++10.18.11 Setting currency/commodity+-----------------------------------++If the currency/commodity symbol is included in the CSV's amount+field(s):++2023-01-01,foo,$123.00++   you don't have to do anything special for the commodity symbol, it+will be assigned as part of the amount.  Eg:++fields date,description,amount++2023-01-01 foo+    expenses:unknown         $123.00+    income:unknown          $-123.00++   If the currency is provided as a separate CSV field:++2023-01-01,foo,USD,123.00++   You can assign that to the 'currency' pseudo-field, which has the+special effect of prepending itself to every amount in the transaction+(on the left, with no separating space):++fields date,description,currency,amount++2023-01-01 foo+    expenses:unknown       USD123.00+    income:unknown        USD-123.00++   Or, you can use a field assignment to construct the amount yourself,+with more control.  Eg to put the symbol on the right, and separated by+a space:++fields date,description,cur,amt+amount %amt %cur++2023-01-01 foo+    expenses:unknown        123.00 USD+    income:unknown         -123.00 USD++   Note we used a temporary field name ('cur') that is not 'currency' -+that would trigger the prepending effect, which we don't want here.+++File: hledger.info,  Node: Amount decimal places,  Next: Referencing other fields,  Prev: Setting currency/commodity,  Up: Working with CSV++10.18.12 Amount decimal places+------------------------------++Like amounts in a journal file, the amounts generated by CSV rules like+'amount1' influence commodity display styles, such as the number of+decimal places displayed in reports.++   The original amounts as written in the CSV file do not affect display+style (because we don't yet reliably know their commodity).+++File: hledger.info,  Node: Referencing other fields,  Next: How CSV rules are evaluated,  Prev: Amount decimal places,  Up: Working with CSV++10.18.13 Referencing other fields+---------------------------------++In field assignments, you can interpolate only CSV fields, not hledger+fields.  In the example below, there's both a CSV field and a hledger+field named amount1, but %amount1 always means the CSV field, not the+hledger field:++# Name the third CSV field "amount1"+fields date,description,amount1++# Set hledger's amount1 to the CSV amount1 field followed by USD+amount1 %amount1 USD++# Set comment to the CSV amount1 (not the amount1 assigned above)+comment %amount1++   Here, since there's no CSV amount1 field, %amount1 will produce a+literal "amount1":++fields date,description,csvamount+amount1 %csvamount USD+# Can't interpolate amount1 here+comment %amount1++   When there are multiple field assignments to the same hledger field,+only the last one takes effect.  Here, comment's value will be be B, or+C if "something" is matched, but never A:++comment A+comment B+if something+ comment C+++File: hledger.info,  Node: How CSV rules are evaluated,  Next: Well factored rules,  Prev: Referencing other fields,  Up: Working with CSV++10.18.14 How CSV rules are evaluated+------------------------------------++Here's how to think of CSV rules being evaluated (if you really need+to).  First,++   * 'include' - all includes are inlined, from top to bottom, depth+     first.  (At each include point the file is inlined and scanned for+     further includes, recursively, before proceeding.)++   Then "global" rules are evaluated, top to bottom.  If a rule is+repeated, the last one wins:++   * 'skip' (at top level)+   * 'date-format'+   * 'newest-first'+   * 'fields' - names the CSV fields, optionally sets up initial+     assignments to hledger fields++   Then for each CSV record in turn:++   * test all 'if' blocks.  If any of them contain a 'end' rule, skip+     all remaining CSV records.  Otherwise if any of them contain a+     'skip' rule, skip that many CSV records.  If there are multiple+     matched 'skip' rules, the first one wins.+   * collect all field assignments at top level and in matched 'if'+     blocks.  When there are multiple assignments for a field, keep only+     the last one.+   * compute a value for each hledger field - either the one that was+     assigned to it (and interpolate the %CSVFIELD references), or a+     default+   * generate a hledger transaction (journal entry) from these values.++   This is all part of the CSV reader, one of several readers hledger+can use to parse input files.  When all files have been read+successfully, the transactions are passed as input to whichever hledger+command the user specified.+++File: hledger.info,  Node: Well factored rules,  Prev: How CSV rules are evaluated,  Up: Working with CSV++10.18.15 Well factored rules+----------------------------++Some things than can help reduce duplication and complexity in rules+files:++   * Extracting common rules usable with multiple CSV files into a+     'common.rules', and adding 'include common.rules' to each CSV's+     rules file.++   * Splitting if blocks into smaller if blocks, extracting the+     frequently used parts.+++File: hledger.info,  Node: CSV rules examples,  Prev: Working with CSV,  Up: CSV++10.19 CSV rules examples+========================++* Menu:++* Bank of Ireland::+* Coinbase::+* Amazon::+* Paypal::+++File: hledger.info,  Node: Bank of Ireland,  Next: Coinbase,  Up: CSV rules examples++10.19.1 Bank of Ireland+-----------------------++Here's a CSV with two amount fields (Debit and Credit), and a balance+field, which we can use to add balance assertions, which is not+necessary but provides extra error checking:++Date,Details,Debit,Credit,Balance+07/12/2012,LODGMENT       529898,,10.0,131.21+07/12/2012,PAYMENT,5,,126++# bankofireland-checking.csv.rules++# skip the header line+skip++# name the csv fields, and assign some of them as journal entry fields+fields  date, description, amount-out, amount-in, balance++# We generate balance assertions by assigning to "balance"+# above, but you may sometimes need to remove these because:+#+# - the CSV balance differs from the true balance,+#   by up to 0.0000000000005 in my experience+#+# - it is sometimes calculated based on non-chronological ordering,+#   eg when multiple transactions clear on the same day++# date is in UK/Ireland format+date-format  %d/%m/%Y++# set the currency+currency  EUR++# set the base account for all txns+account1  assets:bank:boi:checking++$ hledger -f bankofireland-checking.csv print+2012-12-07 LODGMENT       529898+    assets:bank:boi:checking         EUR10.0 = EUR131.2+    income:unknown                  EUR-10.0++2012-12-07 PAYMENT+    assets:bank:boi:checking         EUR-5.0 = EUR126.0+    expenses:unknown                  EUR5.0++   The balance assertions don't raise an error above, because we're+reading directly from CSV, but they will be checked if these entries are+imported into a journal file.+++File: hledger.info,  Node: Coinbase,  Next: Amazon,  Prev: Bank of Ireland,  Up: CSV rules examples++10.19.2 Coinbase+----------------++A simple example with some CSV from Coinbase.  The spot price is+recorded using cost notation.  The legacy 'amount' field name+conveniently sets amount 2 (posting 2's amount) to the total cost.++# Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes+# 2021-12-30T06:57:59Z,Receive,USDC,100,GBP,0.740000,"","","","Received 100.00 USDC from an external account"++# coinbase.csv.rules+skip         1+fields       Timestamp,Transaction_Type,Asset,Quantity_Transacted,Spot_Price_Currency,Spot_Price_at_Transaction,Subtotal,Total,Fees_Spread,Notes+date         %Timestamp+date-format  %Y-%m-%dT%T%Z+description  %Notes+account1     assets:coinbase:cc+amount       %Quantity_Transacted %Asset @ %Spot_Price_at_Transaction %Spot_Price_Currency++$ hledger print -f coinbase.csv+2021-12-30 Received 100.00 USDC from an external account+    assets:coinbase:cc    100 USDC @ 0.740000 GBP+    income:unknown                 -74.000000 GBP+++File: hledger.info,  Node: Amazon,  Next: Paypal,  Prev: Coinbase,  Up: CSV rules examples++10.19.3 Amazon+--------------++Here we convert amazon.com order history, and use an if block to+generate a third posting if there's a fee.  (In practice you'd probably+get this data from your bank instead, but it's an example.)++"Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID"+"Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL"+"Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL"++# amazon-orders.csv.rules++# skip one header line+skip 1++# name the csv fields, and assign the transaction's date, amount and code.+# Avoided the "status" and "amount" hledger field names to prevent confusion.+fields date, _, toorfrom, name, amzstatus, amzamount, fees, code++# how to parse the date+date-format %b %-d, %Y++# combine two fields to make the description+description %toorfrom %name++# save the status as a tag+comment     status:%amzstatus++# set the base account for all transactions+account1    assets:amazon+# leave amount1 blank so it can balance the other(s).+# I'm assuming amzamount excludes the fees, don't remember++# set a generic account2+account2    expenses:misc+amount2     %amzamount+# and maybe refine it further:+#include categorisation.rules++# add a third posting for fees, but only if they are non-zero.+if %fees [1-9]+ account3    expenses:fees+ amount3     %fees++$ hledger -f amazon-orders.csv print+2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo.  ; status:Completed+    assets:amazon+    expenses:misc          $20.00++2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc.  ; status:Completed+    assets:amazon+    expenses:misc          $25.00+    expenses:fees           $1.00+++File: hledger.info,  Node: Paypal,  Prev: Amazon,  Up: CSV rules examples++10.19.4 Paypal+--------------++Here's a real-world rules file for (customised) Paypal CSV, with some+Paypal-specific rules, and a second rules file included:++"Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"+"10/01/2019","03:46:20","PDT","Calm Radio","Subscription Payment","Completed","USD","-6.99","0.00","-6.99","simon@joyful.com","memberships@calmradio.com","60P57143A8206782E","MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month","","I-R8YLY094FJYR","","-6.99",""+"10/01/2019","03:46:20","PDT","","Bank Deposit to PP Account ","Pending","USD","6.99","0.00","6.99","","simon@joyful.com","0TU1544T080463733","","","60P57143A8206782E","","0.00",""+"10/01/2019","08:57:01","PDT","Patreon","PreApproved Payment Bill User Payment","Completed","USD","-7.00","0.00","-7.00","simon@joyful.com","support@patreon.com","2722394R5F586712G","Patreon* Membership","","B-0PG93074E7M86381M","","-7.00",""+"10/01/2019","08:57:01","PDT","","Bank Deposit to PP Account ","Pending","USD","7.00","0.00","7.00","","simon@joyful.com","71854087RG994194F","Patreon* Membership","","2722394R5F586712G","","0.00",""+"10/19/2019","03:02:12","PDT","Wikimedia Foundation, Inc.","Subscription Payment","Completed","USD","-2.00","0.00","-2.00","simon@joyful.com","tle@wikimedia.org","K9U43044RY432050M","Monthly donation to the Wikimedia Foundation","","I-R5C3YUS3285L","","-2.00",""+"10/19/2019","03:02:12","PDT","","Bank Deposit to PP Account ","Pending","USD","2.00","0.00","2.00","","simon@joyful.com","3XJ107139A851061F","","","K9U43044RY432050M","","0.00",""+"10/22/2019","05:07:06","PDT","Noble Benefactor","Subscription Payment","Completed","USD","10.00","-0.59","9.41","noble@bene.fac.tor","simon@joyful.com","6L8L1662YP1334033","Joyful Systems","","I-KC9VBGY2GWDB","","9.41",""++# paypal-custom.csv.rules++# Tips:+# Export from Activity -> Statements -> Custom -> Activity download+# Suggested transaction type: "Balance affecting"+# Paypal's default fields in 2018 were:+# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Shipping Address","Address Status","Item Title","Item ID","Shipping and Handling Amount","Insurance Amount","Sales Tax","Option 1 Name","Option 1 Value","Option 2 Name","Option 2 Value","Reference Txn ID","Invoice Number","Custom Number","Quantity","Receipt ID","Balance","Address Line 1","Address Line 2/District/Neighborhood","Town/City","State/Province/Region/County/Territory/Prefecture/Republic","Zip/Postal Code","Country","Contact Phone Number","Subject","Note","Country Code","Balance Impact"+# This rules file assumes the following more detailed fields, configured in "Customize report fields":+# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"++fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note++skip  1++date-format  %-m/%-d/%Y++# ignore some paypal events+if+In Progress+Temporary Hold+Update to+ skip++# add more fields to the description+description %description_ %itemtitle++# save some other fields as tags+comment  itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_++# convert to short currency symbols+if %currency USD+ currency $+if %currency EUR+ currency E+if %currency GBP+ currency P++# generate postings++# the first posting will be the money leaving/entering my paypal account+# (negative means leaving my account, in all amount fields)+account1 assets:online:paypal+amount1  %netamount++# the second posting will be money sent to/received from other party+# (account2 is set below)+amount2  -%grossamount++# if there's a fee, add a third posting for the money taken by paypal.+if %feeamount [1-9]+ account3 expenses:banking:paypal+ amount3  -%feeamount+ comment3 business:++# choose an account for the second posting++# override the default account names:+# if the amount is positive, it's income (a debit)+if %grossamount ^[^-]+ account2 income:unknown+# if negative, it's an expense (a credit)+if %grossamount ^-+ account2 expenses:unknown++# apply common rules for setting account2 & other tweaks+include common.rules++# apply some overrides specific to this csv++# Transfers from/to bank. These are usually marked Pending,+# which can be disregarded in this case.+if+Bank Account+Bank Deposit to PP Account+ description %type for %referencetxnid %itemtitle+ account2 assets:bank:wf:pchecking+ account1 assets:online:paypal++# Currency conversions+if Currency Conversion+ account2 equity:currency conversion++# common.rules++if+darcs+noble benefactor+ account2 revenues:foss donations:darcshub+ comment2 business:++if+Calm Radio+ account2 expenses:online:apps++if+electronic frontier foundation+Patreon+wikimedia+Advent of Code+ account2 expenses:dues++if Google+ account2 expenses:online:apps+ description google | music++$ hledger -f paypal-custom.csv  print+2019-10-01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month  ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed+    assets:online:paypal          $-6.99 = $-6.99+    expenses:online:apps           $6.99++2019-10-01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E  ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending+    assets:online:paypal               $6.99 = $0.00+    assets:bank:wf:pchecking          $-6.99++2019-10-01 (2722394R5F586712G) Patreon Patreon* Membership  ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed+    assets:online:paypal          $-7.00 = $-7.00+    expenses:dues                  $7.00++2019-10-01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership  ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending+    assets:online:paypal               $7.00 = $0.00+    assets:bank:wf:pchecking          $-7.00++2019-10-19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation  ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed+    assets:online:paypal             $-2.00 = $-2.00+    expenses:dues                     $2.00+    expenses:banking:paypal      ; business:++2019-10-19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M  ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending+    assets:online:paypal               $2.00 = $0.00+    assets:bank:wf:pchecking          $-2.00++2019-10-22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems  ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed+    assets:online:paypal                       $9.41 = $9.41+    revenues:foss donations:darcshub         $-10.00  ; business:+    expenses:banking:paypal                    $0.59  ; business:+++File: hledger.info,  Node: Timeclock,  Next: Timedot,  Prev: CSV,  Up: Top++11 Timeclock+************++The time logging format of timeclock.el, as read by hledger.++   hledger can read time logs in timeclock format.  As with Ledger,+these are (a subset of) timeclock.el's format, containing clock-in and+clock-out entries as in the example below.  The date is a simple date.+The time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are+optional.  The timezone, if present, must be four digits and is ignored+(currently the time is always interpreted as a local time).  Lines+beginning with '#' or ';' or '*', and blank lines, are ignored.++i 2015/03/30 09:00:00 some account  optional description after 2 spaces ; optional comment, tags:+o 2015/03/30 09:20:00+i 2015/03/31 22:21:45 another:account+o 2015/04/01 02:00:34++   hledger treats each clock-in/clock-out pair as a transaction posting+some number of hours to an account.  Or if the session spans more than+one day, it is split into several transactions, one for each day.  For+the above time log, 'hledger print' generates these journal entries:++$ hledger -f t.timeclock print+2015-03-30 * optional description after 2 spaces   ; optional comment, tags:+    (some account)           0.33h++2015-03-31 * 22:21-23:59+    (another:account)           1.64h++2015-04-01 * 00:00-02:00+    (another:account)           2.01h++   Here is a sample.timeclock to download and some queries to try:++$ hledger -f sample.timeclock balance                               # current time balances+$ hledger -f sample.timeclock register -p 2009/3                    # sessions in march 2009+$ hledger -f sample.timeclock register -p weekly --depth 1 --empty  # time summary by week++   To generate time logs, ie to clock in and clock out, you could:++   * use emacs and the built-in timeclock.el, or the extended+     timeclock-x.el and perhaps the extras in ledgerutils.el++   * at the command line, use these bash aliases: 'shell alias ti="echo+     i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o+     `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"'++   * or use the old 'ti' and 'to' scripts in the ledger 2.x repository.+     These rely on a "timeclock" executable which I think is just the+     ledger 2 executable renamed.+++File: hledger.info,  Node: Timedot,  Next: PART 3 REPORTING CONCEPTS,  Prev: Timeclock,  Up: Top++12 Timedot+**********++'timedot' format is hledger's human-friendly time logging format.+Compared to 'timeclock' format, it is more convenient for quick,+approximate, and retroactive time logging, and more human-readable (you+can see at a glance where time was spent).  A quick example:++2023-05-01+hom:errands          .... ....  ; two hours; the space is ignored+fos:hledger:timedot  ..         ; half an hour+per:admin:finance               ; no time spent yet++   hledger reads this as a transaction on this day with three+(unbalanced) postings, where each dot represents "0.25".  No commodity+symbol is assumed, but we typically interpret it as hours.++$ hledger -f a.timedot print   # .timedot file extension (or timedot: prefix) is required+2023-05-01 *+    (hom:errands)                    2.00  ; two hours+    (fos:hledger:timedot)            0.50  ; half an hour+    (per:admin:finance)                 0++   A timedot file contains a series of transactions (usually one per+day).  Each begins with a *simple date* (Y-M-D, Y/M/D, or Y.M.D),+optionally be followed on the same line by a transaction description,+and/or a transaction comment following a semicolon.++   After the date line are zero or more time postings, consisting of:++   * *An account name* - any hledger-style account name, optionally+     indented.++   * *Two or more spaces* - required if there is an amount (as in+     journal format).++   * *A timedot amount*, which can be++        * empty (representing zero)++        * a number, optionally followed by a unit 's', 'm', 'h', 'd',+          'w', 'mo', or 'y', representing a precise number of seconds,+          minutes, hours, days weeks, months or years (hours is assumed+          by default), which will be converted to hours according to 60s+          = 1m, 60m = 1h, 24h = 1d, 7d = 1w, 30d = 1mo, 365d = 1y.++        * one or more dots (period characters), each representing 0.25.+          These are the dots in "timedot".  Spaces are ignored and can+          be used for grouping/alignment.++        * one or more letters.  These are like dots but they also+          generate a tag 't:' (short for "type") with the letter as its+          value, and a separate posting for each of the values.  This+          provides a second dimension of categorisation, viewable in+          reports with '--pivot t'.++   * *An optional comment* following a semicolon (a hledger-style+     posting comment).++   There is some flexibility to help with keeping time log data and+notes in the same file:++   * Blank lines and lines beginning with '#' or ';' are ignored.++   * After the first date line, lines which do not contain a double+     space are parsed as postings with zero amount.  (hledger's register+     reports will show these if you add -E).++   * Before the first date line, lines beginning with '*' (eg org+     headings) are ignored.  And from the first date line onward, Emacs+     org mode heading prefixes at the start of lines (one or more '*''s+     followed by a space) will be ignored.  This means the time log can+     also be a org outline.++* Menu:++* Timedot examples::+++File: hledger.info,  Node: Timedot examples,  Up: Timedot++12.1 Timedot examples+=====================++Numbers:++2016/2/3+inc:client1   4+fos:hledger   3h+biz:research  60m++   Dots:++# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.+2016/2/1+inc:client1   .... .... .... .... .... ....+fos:haskell   .... ..+biz:research  .++2016/2/2+inc:client1   .... ....+biz:research  .++$ hledger -f a.timedot print date:2016/2/2+2016-02-02 *+    (inc:client1)          2.00++2016-02-02 *+    (biz:research)          0.25++$ hledger -f a.timedot bal --daily --tree+Balance changes in 2016-02-01-2016-02-03:++            ||  2016-02-01d  2016-02-02d  2016-02-03d +============++========================================+ biz        ||         0.25         0.25         1.00 +   research ||         0.25         0.25         1.00 + fos        ||         1.50            0         3.00 +   haskell  ||         1.50            0            0 +   hledger  ||            0            0         3.00 + inc        ||         6.00         2.00         4.00 +   client1  ||         6.00         2.00         4.00 +------------++----------------------------------------+            ||         7.75         2.25         8.00 ++   Letters:++# Activity types:+#  c cleanup/catchup/repair+#  e enhancement+#  s support+#  l learning/research++2023-11-01+work:adm  ccecces++$ hledger -f a.timedot print+2023-11-01+    (work:adm)  1     ; t:c+    (work:adm)  0.5   ; t:e+    (work:adm)  0.25  ; t:s++$ hledger -f a.timedot bal+                1.75  work:adm+--------------------+                1.75  ++$ hledger -f a.timedot bal --pivot t+                1.00  c+                0.50  e+                0.25  s+--------------------+                1.75  ++   Org:++* 2023 Work Diary+** Q1+*** 2023-02-29+**** DONE+0700 yoga+**** UNPLANNED+**** BEGUN+hom:chores+ cleaning  ...+ water plants+  outdoor - one full watering can+  indoor - light watering+**** TODO+adm:planning: trip+*** LATER++   Using '.' as account name separator:++2016/2/4+fos.hledger.timedot  4h+fos.ledger           ..++$ hledger -f a.timedot --alias '/\./=:' bal -t+                4.50  fos+                4.00    hledger:timedot+                0.50    ledger+--------------------+                4.50+++File: hledger.info,  Node: PART 3 REPORTING CONCEPTS,  Next: Amount formatting parseability,  Prev: Timedot,  Up: Top++13 PART 3: REPORTING CONCEPTS+*****************************+++File: hledger.info,  Node: Amount formatting parseability,  Next: Time periods,  Prev: PART 3 REPORTING CONCEPTS,  Up: Top++14 Amount formatting, parseability+**********************************++If you're wondering why your 'print' report sometimes shows trailing+decimal marks, with no decimal digits; it does this when showing amounts+that have digit group marks but no decimal digits, to disambiguate them+and allow them to be re-parsed reliably (see also Decimal marks, digit+group marks.  Eg:++commodity $1,000.00++2023-01-02+    (a)      $1000++$ hledger print+2023-01-02+    (a)        $1,000.++   If this is a problem (eg when exporting to Ledger), you can avoid it+by disabling digit group marks, eg with -c/-commodity (for each affected+commodity):++$ hledger print -c '$1000.00'+2023-01-02+    (a)          $1000++   or by forcing print to always show decimal digits, with -round:++$ hledger print -c '$1,000.00' --round=soft+2023-01-02+    (a)      $1,000.00++   More generally: hledger output falls into three rough categories,+which format amounts a little bit differently to suit different+consumers:++   *1.  "hledger-readable output" - should be readable by hledger (and+by humans)*++   * This is produced by reports that show full journal entries:+     'print', 'import', 'close', 'rewrite' etc.+   * It shows amounts with their original journal precisions, which may+     not be consistent.+   * It adds a trailing decimal mark when needed to avoid showing+     ambiguous amounts.+   * It can be parsed reliably (by hledger and ledger2beancount at+     least, but perhaps not by Ledger..)++   *2.  "human-readable output" - usually for humans*++   * This is produced by all other reports.+   * It shows amounts with standard display precisions, which will be+     consistent within each commodity.+   * It shows ambiguous amounts unmodified.+   * It can be parsed reliably in the context of a known report (when+     you know decimals are consistently not being shown, you can assume+     a single mark is a digit group mark).++   *3.  "machine-readable output" - usually for other software*++   * This is produced by all reports when an output format like 'csv',+     'tsv', 'json', or 'sql' is selected.+   * It shows amounts as 1 or 2 do, but without digit group marks.+   * It can be parsed reliably (if needed, the decimal mark can be+     changed with -c/-commodity-style).+++File: hledger.info,  Node: Time periods,  Next: Depth,  Prev: Amount formatting parseability,  Up: Top++15 Time periods+***************++* Menu:++* Report start & end date::+* Smart dates::+* Report intervals::+* Date adjustment::+* Period expressions::+++File: hledger.info,  Node: Report start & end date,  Next: Smart dates,  Up: Time periods++15.1 Report start & end date+============================++By default, most hledger reports will show the full span of time+represented by the journal.  The report start date will be the earliest+transaction or posting date, and the report end date will be the latest+transaction, posting, or market price date.++   Often you will want to see a shorter time span, such as the current+month.  You can specify a start and/or end date using '-b/--begin',+'-e/--end', '-p/--period' or a 'date:' query (described below).  All of+these accept the smart date syntax (below).++   Some notes:++   * End dates are exclusive, as in Ledger, so you should write the date+     _after_ the last day you want to see in the report.+   * As noted in reporting options: among start/end dates specified with+     _options_, the last (i.e.  right-most) option takes precedence.+   * The effective report start and end dates are the intersection of+     the start/end dates from options and that from 'date:' queries.+     That is, 'date:2019-01 date:2019 -p'2000 to 2030'' yields January+     2019, the smallest common time span.+   * In some cases a report interval will adjust start/end dates to fall+     on interval boundaries (see below).++   Examples:++'-b           begin on St. Patrick's day 2016+2016/3/17'+'-e 12/1'     end at the start of december 1st of the current year+              (11/30 will be the last date included)+'-b           all transactions on or after the 1st of the current month+thismonth'+'-p           all transactions in the current month+thismonth'+'date:2016/3/17..'the above written as queries instead ('..' can also be+              replaced with '-')+'date:..12/1'+'date:thismonth..'+'date:thismonth'+++File: hledger.info,  Node: Smart dates,  Next: Report intervals,  Prev: Report start & end date,  Up: Time periods++15.2 Smart dates+================++hledger's user interfaces accept a "smart date" syntax for added+convenience.  Smart dates optionally can be relative to today's date, be+written with english words, and have less-significant parts omitted+(missing parts are inferred as 1).  Some examples:++'2004/10/1',              exact date, several separators allowed.  Year+'2004-01-01',             is 4+ digits, month is 1-12, day is 1-31+'2004.9.1'+'2004'                    start of year+'2004/10'                 start of month+'10/1'                    month and day in current year+'21'                      day in current month+'october, oct'            start of month in current year+'yesterday, today,        -1, 0, 1 days from today+tomorrow'+'last/this/next           -1, 0, 1 periods from the current period+day/week/month/quarter/year'+'in n                     n periods from the current period+days/weeks/months/quarters/years'+'n                        n periods from the current period+days/weeks/months/quarters/years+ahead'+'n                        -n periods from the current period+days/weeks/months/quarters/years+ago'+'20181201'                8 digit YYYYMMDD with valid year month and+                          day+'201812'                  6 digit YYYYMM with valid year and month++   Some counterexamples - malformed digit sequences might give+surprising results:++'201813'     6 digits with an invalid month is parsed as start of+             6-digit year+'20181301'   8 digits with an invalid month is parsed as start of+             8-digit year+'20181232'   8 digits with an invalid day gives an error+'201801012'  9+ digits beginning with a valid YYYYMMDD gives an error++   "Today's date" can be overridden with the '--today' option, in case+it's needed for testing or for recreating old reports.  (Except for+periodic transaction rules, which are not affected by '--today'.)+++File: hledger.info,  Node: Report intervals,  Next: Date adjustment,  Prev: Smart dates,  Up: Time periods++15.3 Report intervals+=====================++A report interval can be specified so that reports like register,+balance or activity become multi-period, showing each subperiod as a+separate row or column.++   The following standard intervals can be enabled with command-line+flags:++   * '-D/--daily'+   * '-W/--weekly'+   * '-M/--monthly'+   * '-Q/--quarterly'+   * '-Y/--yearly'++   More complex intervals can be specified using '-p/--period',+described below.+++File: hledger.info,  Node: Date adjustment,  Next: Period expressions,  Prev: Report intervals,  Up: Time periods++15.4 Date adjustment+====================++When there is a report interval (other than daily), report start/end+dates which have been inferred, eg from the journal, are automatically+adjusted to natural period boundaries.  This is convenient for producing+simple periodic reports.  More precisely:++   * an inferred start date will be adjusted earlier if needed to fall+     on a natural period boundary++   * an inferred end date will be adjusted later if needed to make the+     last period the same length as the others.++   By contrast, start/end dates which have been specified explicitly,+with '-b', '-e', '-p' or 'date:', will not be adjusted (since hledger+1.29).  This makes it possible to specify non-standard report periods,+but it also means that if you are specifying a start date, you should+pick one that's on a period boundary if you want to see simple report+period headings.+++File: hledger.info,  Node: Period expressions,  Prev: Date adjustment,  Up: Time periods++15.5 Period expressions+=======================++The '-p/--period' option specifies a period expression, which is a+compact way of expressing a start date, end date, and/or report+interval.++   Here's a period expression with a start and end date (specifying the+first quarter of 2009):++'-p "from 2009/1/1 to 2009/4/1"'++   Several keywords like "from" and "to" are supported for readability;+these are optional.  "to" can also be written as ".."  or "-".  The+spaces are also optional, as long as you don't run two dates together.+So the following are equivalent to the above:++'-p "2009/1/1 2009/4/1"'+'-p2009/1/1to2009/4/1'+'-p2009/1/1..2009/4/1'++   Dates are smart dates, so if the current year is 2009, these are also+equivalent to the above:++'-p "1/1 4/1"'+'-p "jan-apr"'+'-p "this year to 4/1"'++   If you specify only one date, the missing start or end date will be+the earliest or latest transaction date in the journal:++'-p "from 2009/1/1"'   everything after january 1, 2009+'-p "since 2009/1"'    the same, since is a synonym+'-p "from 2009"'       the same+'-p "to 2009"'         everything before january 1, 2009++   You can also specify a period by writing a single partial or full+date:++'-p "2009"'     the year 2009; equivalent to “2009/1/1 to 2010/1/1”+'-p "2009/1"'   the month of january 2009; equivalent to “2009/1/1 to+                2009/2/1”+'-p             the first day of 2009; equivalent to “2009/1/1 to+"2009/1/1"'     2009/1/2”++   or by using the "Q" quarter-year syntax (case insensitive):++'-p "2009Q1"'    first quarter of 2009, equivalent to “2009/1/1 to+                 2009/4/1”+'-p "q4"'        fourth quarter of the current year++* Menu:++* Period expressions with a report interval::+* More complex report intervals::+* Multiple weekday intervals::+++File: hledger.info,  Node: Period expressions with a report interval,  Next: More complex report intervals,  Up: Period expressions++15.5.1 Period expressions with a report interval+------------------------------------------------++A period expression can also begin with a report interval, separated+from the start/end dates (if any) by a space or the word 'in':++'-p "weekly from 2009/1/1 to 2009/4/1"'+'-p "monthly in 2008"'+'-p "quarterly"'+++File: hledger.info,  Node: More complex report intervals,  Next: Multiple weekday intervals,  Prev: Period expressions with a report interval,  Up: Period expressions++15.5.2 More complex report intervals+------------------------------------++Some more complex intervals can be specified within period expressions,+such as:++   * 'biweekly' (every two weeks)+   * 'fortnightly'+   * 'bimonthly' (every two months)+   * 'every day|week|month|quarter|year'+   * 'every N days|weeks|months|quarters|years'++   Weekly on a custom day:++   * 'every Nth day of week' ('th', 'nd', 'rd', or 'st' are all accepted+     after the number)+   * 'every WEEKDAYNAME' (full or three-letter english weekday name,+     case insensitive)++   Monthly on a custom day:++   * 'every Nth day [of month]'+   * 'every Nth WEEKDAYNAME [of month]'++   Yearly on a custom day:++   * 'every MM/DD [of year]' (month number and day of month number)+   * 'every MONTHNAME DDth [of year]' (full or three-letter english+     month name, case insensitive, and day of month number)+   * 'every DDth MONTHNAME [of year]' (equivalent to the above)++   Examples:++'-p "bimonthly from+2008"'+'-p "every 2 weeks"'+'-p "every 5 months from+2009/03"'+'-p "every 2nd day of       periods will go from Tue to Tue+week"'+'-p "every Tue"'            same+'-p "every 15th day"'       period boundaries will be on 15th of each+                            month+'-p "every 2nd Monday"'     period boundaries will be on second Monday+                            of each month+'-p "every 11/05"'          yearly periods with boundaries on 5th of+                            November+'-p "every 5th November"'   same+'-p "every Nov 5th"'        same++   Show historical balances at end of the 15th day of each month (N is+an end date, exclusive as always):++$ hledger balance -H -p "every 16th day"++   Group postings from the start of wednesday to end of the following+tuesday (N is both (inclusive) start date and (exclusive) end date):++$ hledger register checking -p "every 3rd day of week"+++File: hledger.info,  Node: Multiple weekday intervals,  Prev: More complex report intervals,  Up: Period expressions++15.5.3 Multiple weekday intervals+---------------------------------++This special form is also supported:++   * 'every WEEKDAYNAME,WEEKDAYNAME,...' (full or three-letter english+     weekday names, case insensitive)++   Also, 'weekday' and 'weekendday' are shorthand for+'mon,tue,wed,thu,fri' and 'sat,sun'.++   This is mainly intended for use with '--forecast', to generate+periodic transactions on arbitrary days of the week.  It may be less+useful with '-p', since it divides each week into subperiods of unequal+length, which is unusual.  (Related: #1632)++   Examples:++'-p "every         dates will be Mon, Wed, Fri; periods will be+mon,wed,fri"'      Mon-Tue, Wed-Thu, Fri-Sun+'-p "every         dates will be Mon, Tue, Wed, Thu, Fri; periods will+weekday"'          be Mon, Tue, Wed, Thu, Fri-Sun+'-p "every         dates will be Sat, Sun; periods will be Sat, Sun-Fri+weekendday"'+++File: hledger.info,  Node: Depth,  Next: Queries,  Prev: Time periods,  Up: Top++16 Depth+********++With the '--depth NUM' option (short form: '-NUM'), reports will show+accounts only to the specified depth, hiding deeper subaccounts.  Use+this when you want a summary with less detail.  This flag has the same+effect as a 'depth:' query argument: 'depth:2', '--depth=2' or '-2' are+equivalent.+++File: hledger.info,  Node: Queries,  Next: Pivoting,  Prev: Depth,  Up: Top++17 Queries+**********++One of hledger's strengths is being able to quickly report on a precise+subset of your data.  Most hledger commands accept optional query+arguments to restrict their scope.  The syntax is as follows:++   * Zero or more space-separated query terms.  These are most often+     account name substrings:++     'utilities food:groceries'++   * Terms with spaces or other special characters should be enclosed in+     quotes:++     '"personal care"'++   * Regular expressions are also supported:++     '"^expenses\b"'+     '"accounts (payable|receivable)"'++   * Add a query type prefix to match other parts of the data:++     'date:202312-'+     'status:'+     'desc:amazon'+     'cur:USD'+     '"amt:>0"'++   * Add a 'not:' prefix to negate:++     'not:cur:USD'++   * Multiple unlike terms are AND-ed, multiple like terms are OR-ed++     'date:2022 desc:amazon desc:amzn'+     (all transactions with "amazon" or "amzn" in description during+     2022)++* Menu:++* Query types::+* Combining query terms::+* Queries and command options::+* Queries and valuation::+* Querying with account aliases::+* Querying with cost or value::+++File: hledger.info,  Node: Query types,  Next: Combining query terms,  Up: Queries++17.1 Query types+================++Here are the types of query term available.  Remember these can also be+prefixed with *'not:'* to convert them into a negative match.++   *'acct:REGEX', 'REGEX'*+Match account names containing this (case insensitive) regular+expression.  This is the default query type when there is no prefix, and+regular expression syntax is typically not needed, so usually we just+write an account name substring, like 'expenses' or 'food'.++   *'amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N'*+Match postings with a single-commodity amount equal to, less than, or+greater than N. (Postings with multi-commodity amounts are not tested+and will always match.)  The comparison has two modes: if N is preceded+by a + or - sign (or is 0), the two signed numbers are compared.+Otherwise, the absolute magnitudes are compared, ignoring sign.++   *'code:REGEX'*+Match by transaction code (eg check number).++   *'cur:REGEX'*+Match postings or transactions including any amounts whose+currency/commodity symbol is fully matched by REGEX. (For a partial+match, use '.*REGEX.*').  Note, to match special characters which are+regex-significant, you need to escape them with '\'.  And for characters+which are significant to your shell you may need one more level of+escaping.  So eg to match the dollar sign:+'hledger print cur:\\$'.++   *'desc:REGEX'*+Match transaction descriptions.++   *'date:PERIODEXPR'*+Match dates (or with the '--date2' flag, secondary dates) within the+specified period.  PERIODEXPR is a period expression with no report+interval.  Examples:+'date:2016', 'date:thismonth', 'date:2/1-2/15',+'date:2021-07-27..nextquarter'.++   *'date2:PERIODEXPR'*+Match secondary dates within the specified period (independent of the+'--date2' flag).++   *'depth:N'*+Match (or display, depending on command) accounts at or above this+depth.++   *'expr:"TERM AND NOT (TERM OR TERM)"'* (eg)+Match with a boolean combination of queries (which must be enclosed in+quotes).  See Combining query terms below.++   *'note:REGEX'*+Match transaction notes (the part of the description right of '|', or+the whole description if there's no '|').++   *'payee:REGEX'*+Match transaction payee/payer names (the part of the description left of+'|', or the whole description if there's no '|').++   *'real:, real:0'*+Match real or virtual postings respectively.++   *'status:, status:!, status:*'*+Match unmarked, pending, or cleared transactions respectively.++   *'type:TYPECODES'*+Match by account type (see Declaring accounts > Account types).+'TYPECODES' is one or more of the single-letter account type codes+'ALERXCV', case insensitive.  Note 'type:A' and 'type:E' will also match+their respective subtypes 'C' (Cash) and 'V' (Conversion).  Certain+kinds of account alias can disrupt account types, see Rewriting accounts+> Aliases and account types.++   *'tag:REGEX[=REGEX]'*+Match by tag name, and optionally also by tag value.  (To match only by+value, use 'tag:.=REGEX'.)++   When querying by tag, note that:++   * Accounts also inherit the tags of their parent accounts+   * Postings also inherit the tags of their account and their+     transaction+   * Transactions also acquire the tags of their postings.++   (*'inacct:ACCTNAME'*+A special query term used automatically in hledger-web only: tells+hledger-web to show the transaction register for an account.)+++File: hledger.info,  Node: Combining query terms,  Next: Queries and command options,  Prev: Query types,  Up: Queries++17.2 Combining query terms+==========================++When given multiple space-separated query terms, most commands select+things which match:++   * any of the description terms AND+   * any of the account terms AND+   * any of the status terms AND+   * all the other terms.++   The print command is a little different, showing transactions which:++   * match any of the description terms AND+   * have any postings matching any of the positive account terms AND+   * have no postings matching any of the negative account terms AND+   * match all the other terms.++   We also support more complex boolean queries with the 'expr:' prefix.+This allows one to combine queries using one of three operators: AND,+OR, and NOT, where NOT is different syntax for 'not:'.++   Examples of such queries are:++   * Match transactions with 'cool' in the description AND with the 'A'+     tag++     'expr:"desc:cool AND tag:A"'++   * Match transactions NOT to the 'expenses:food' account OR with the+     'A' tag++     'expr:"NOT expenses:food OR tag:A"'++   * Match transactions NOT involving the 'expenses:food' account OR+     with the 'A' tag AND involving the 'expenses:drink' account.  (the+     AND is implicitly added by space-separation, following the rules+     above)++     'expr:"expenses:food OR (tag:A expenses:drink)"'+++File: hledger.info,  Node: Queries and command options,  Next: Queries and valuation,  Prev: Combining query terms,  Up: Queries++17.3 Queries and command options+================================++Some queries can also be expressed as command-line options: 'depth:2' is+equivalent to '--depth 2', 'date:2023' is equivalent to '-p 2023', etc.+When you mix command options and query arguments, generally the+resulting query is their intersection.+++File: hledger.info,  Node: Queries and valuation,  Next: Querying with account aliases,  Prev: Queries and command options,  Up: Queries++17.4 Queries and valuation+==========================++When amounts are converted to other commodities in cost or value+reports, 'cur:' and 'amt:' match the old commodity symbol and the old+amount quantity, not the new ones (except in hledger 1.22.0 where it's+reversed, see #1625).+++File: hledger.info,  Node: Querying with account aliases,  Next: Querying with cost or value,  Prev: Queries and valuation,  Up: Queries++17.5 Querying with account aliases+==================================++When account names are rewritten with '--alias' or 'alias', note that+'acct:' will match either the old or the new account name.+++File: hledger.info,  Node: Querying with cost or value,  Prev: Querying with account aliases,  Up: Queries++17.6 Querying with cost or value+================================++When amounts are converted to other commodities in cost or value+reports, note that 'cur:' matches the new commodity symbol, and not the+old one, and 'amt:' matches the new quantity, and not the old one.+Note: this changed in hledger 1.22, previously it was the reverse, see+the discussion at #1625.+++File: hledger.info,  Node: Pivoting,  Next: Generating data,  Prev: Queries,  Up: Top++18 Pivoting+***********++Normally, hledger groups and sums amounts within each account.  The+'--pivot FIELD' option substitutes some other transaction field for+account names, causing amounts to be grouped and summed by that field's+value instead.  FIELD can be any of the transaction fields 'acct',+'status', 'code', 'desc', 'payee', 'note', or a tag name.  When pivoting+on a tag and a posting has multiple values of that tag, only the first+value is displayed.  Values containing 'colon:separated:parts' will be+displayed hierarchically, like account names.  Multiple, colon-delimited+fields can be pivoted simultaneously, generating a hierarchical account+name.++   Some examples:++2016/02/16 Yearly Dues Payment+    assets:bank account                 2 EUR+    income:dues                        -2 EUR  ; member: John Doe, kind: Lifetime++   Normal balance report showing account names:++$ hledger balance+               2 EUR  assets:bank account+              -2 EUR  income:dues+--------------------+                   0++   Pivoted balance report, using member: tag values instead:++$ hledger balance --pivot member+               2 EUR+              -2 EUR  John Doe+--------------------+                   0++   One way to show only amounts with a member: value (using a query):++$ hledger balance --pivot member tag:member=.+              -2 EUR  John Doe+--------------------+              -2 EUR++   Another way (the acct: query matches against the pivoted "account+name"):++$ hledger balance --pivot member acct:.+              -2 EUR  John Doe+--------------------+              -2 EUR++   Hierarchical reports can be generated with multiple pivots:++$ hledger balance Income:Dues --pivot kind:member+              -2 EUR  Lifetime:John Doe+--------------------+              -2 EUR+++File: hledger.info,  Node: Generating data,  Next: Forecasting,  Prev: Pivoting,  Up: Top++19 Generating data+******************++hledger has several features for generating data, such as:++   * Periodic transaction rules can generate single or repeating+     transactions following a template.  These are usually dated in the+     future, eg to help with forecasting.  They are activated by the+     '--forecast' option.++   * The balance command's '--budget' option uses these same periodic+     rules to generate goals for the budget report.++   * Auto posting rules can generate extra postings on certain matched+     transactions.  They are always applied to forecast transactions;+     with the '--auto' flag they are applied to transactions recorded in+     the journal as well.++   * The '--infer-equity' flag infers missing conversion equity postings+     from @/@@ costs.  And the inverse '--infer-costs' flag infers+     missing @/@@ costs from conversion equity postings.++   Generated data of this kind is temporary, existing only at report+time.  But you can see it in the output of 'hledger print', and you can+save that to your journal, in effect converting it from temporary+generated data to permanent recorded data.  This could be useful as a+data entry aid.++   If you are wondering what data is being generated and why, add the+'--verbose-tags' flag.  In 'hledger print' output you will see extra+tags like 'generated-transaction', 'generated-posting', and 'modified'+on generated/modified data.  Also, even without '--verbose-tags',+generated data always has equivalen hidden tags (with an underscore+prefix), so eg you could match generated transactions with+'tag:_generated-transaction'.+++File: hledger.info,  Node: Forecasting,  Next: Budgeting,  Prev: Generating data,  Up: Top++20 Forecasting+**************++Forecasting, or speculative future reporting, can be useful for+estimating future balances, or for exploring different future scenarios.++   The simplest and most flexible way to do it with hledger is to+manually record a bunch of future-dated transactions.  You could keep+these in a separate 'future.journal' and include that with '-f' only+when you want to see them.++* Menu:++* --forecast::+* Inspecting forecast transactions::+* Forecast reports::+* Forecast tags::+* Forecast period in detail::+* Forecast troubleshooting::+++File: hledger.info,  Node: --forecast,  Next: Inspecting forecast transactions,  Up: Forecasting++20.1 -forecast+==============++There is another way: with the '--forecast' option, hledger can generate+temporary "forecast transactions" for reporting purposes, according to+periodic transaction rules defined in the journal.  Each rule can+generate multiple recurring transactions, so by changing one rule you+can change many forecasted transactions.  (These same rules can also+generate budget goals, described in Budgeting.)++   Forecast transactions usually start after ordinary transactions end.+By default, they begin after your latest-dated ordinary transaction, or+today, whichever is later, and they end six months from today.  (The+exact rules are a little more complicated, and are given below.)++   This is the "forecast period", which need not be the same as the+report period.  You can override it - eg to forecast farther into the+future, or to force forecast transactions to overlap your ordinary+transactions - by giving the -forecast option a period expression+argument, like '--forecast=..2099' or '--forecast=2023-02-15..'.  Note+that the '=' is required.+++File: hledger.info,  Node: Inspecting forecast transactions,  Next: Forecast reports,  Prev: --forecast,  Up: Forecasting++20.2 Inspecting forecast transactions+=====================================++'print' is the best command for inspecting and troubleshooting forecast+transactions.  Eg:++~ monthly from 2022-12-20    rent+    assets:bank:checking+    expenses:rent           $1000++$ hledger print --forecast --today=2023/4/21+2023-05-20 rent+    ; generated-transaction: ~ monthly from 2022-12-20+    assets:bank:checking+    expenses:rent                  $1000++2023-06-20 rent+    ; generated-transaction: ~ monthly from 2022-12-20+    assets:bank:checking+    expenses:rent                  $1000++2023-07-20 rent+    ; generated-transaction: ~ monthly from 2022-12-20+    assets:bank:checking+    expenses:rent                  $1000++2023-08-20 rent+    ; generated-transaction: ~ monthly from 2022-12-20+    assets:bank:checking+    expenses:rent                  $1000++2023-09-20 rent+    ; generated-transaction: ~ monthly from 2022-12-20+    assets:bank:checking+    expenses:rent                  $1000++   Here there are no ordinary transactions, so the forecasted+transactions begin on the first occurence after today's date.  (You+won't normally use '--today'; it's just to make these examples+reproducible.)+++File: hledger.info,  Node: Forecast reports,  Next: Forecast tags,  Prev: Inspecting forecast transactions,  Up: Forecasting++20.3 Forecast reports+=====================++Forecast transactions affect all reports, as you would expect.  Eg:++$ hledger areg rent --forecast --today=2023/4/21+Transactions in expenses:rent and subaccounts:+2023-05-20 rent                 as:ba:checking               $1000         $1000+2023-06-20 rent                 as:ba:checking               $1000         $2000+2023-07-20 rent                 as:ba:checking               $1000         $3000+2023-08-20 rent                 as:ba:checking               $1000         $4000+2023-09-20 rent                 as:ba:checking               $1000         $5000++$ hledger bal -M expenses --forecast --today=2023/4/21+Balance changes in 2023-05-01..2023-09-30:++               ||   May    Jun    Jul    Aug    Sep +===============++===================================+ expenses:rent || $1000  $1000  $1000  $1000  $1000 +---------------++-----------------------------------+               || $1000  $1000  $1000  $1000  $1000 +++File: hledger.info,  Node: Forecast tags,  Next: Forecast period in detail,  Prev: Forecast reports,  Up: Forecasting++20.4 Forecast tags+==================++Forecast transactions generated by -forecast have a hidden tag,+'_generated-transaction'.  So if you ever need to match forecast+transactions, you could use 'tag:_generated-transaction' (or just+'tag:generated') in a query.++   For troubleshooting, you can add the '--verbose-tags' flag.  Then,+visible 'generated-transaction' tags will be added also, so you can view+them with the 'print' command.  Their value indicates which periodic+rule was responsible.+++File: hledger.info,  Node: Forecast period in detail,  Next: Forecast troubleshooting,  Prev: Forecast tags,  Up: Forecasting++20.5 Forecast period, in detail+===============================++Forecast start/end dates are chosen so as to do something useful by+default in almost all situations, while also being flexible.  Here are+(with luck) the exact rules, to help with troubleshooting:++   The forecast period starts on:++   * the later of+        * the start date in the periodic transaction rule+        * the start date in '--forecast''s argument++   * otherwise (if those are not available): the later of+        * the report start date specified with '-b'/'-p'/'date:'+        * the day after the latest ordinary transaction in the journal++   * otherwise (if none of these are available): today.++   The forecast period ends on:++   * the earlier of+        * the end date in the periodic transaction rule+        * the end date in '--forecast''s argument++   * otherwise: the report end date specified with '-e'/'-p'/'date:'+   * otherwise: 180 days (~6 months) from today.+++File: hledger.info,  Node: Forecast troubleshooting,  Prev: Forecast period in detail,  Up: Forecasting++20.6 Forecast troubleshooting+=============================++When -forecast is not doing what you expect, one of these tips should+help:++   * Remember to use the '--forecast' option.+   * Remember to have at least one periodic transaction rule in your+     journal.+   * Test with 'print --forecast'.+   * Check for typos or too-restrictive start/end dates in your periodic+     transaction rule.+   * Leave at least 2 spaces between the rule's period expression and+     description fields.+   * Check for future-dated ordinary transactions suppressing forecasted+     transactions.+   * Try setting explicit report start and/or end dates with '-b', '-e',+     '-p' or 'date:'+   * Try adding the '-E' flag to encourage display of empty periods/zero+     transactions.+   * Try setting explicit forecast start and/or end dates with+     '--forecast=START..END'+   * Consult Forecast period, in detail, above.+   * Check inside the engine: add '--debug=2' (eg).+++File: hledger.info,  Node: Budgeting,  Next: Cost reporting,  Prev: Forecasting,  Up: Top++21 Budgeting+************++With the balance command's '--budget' report, each periodic transaction+rule generates recurring budget goals in specified accounts, and goals+and actual performance can be compared.  See the balance command's doc+below.++   You can generate budget goals and forecast transactions at the same+time, from the same or different periodic transaction rules: 'hledger+bal -M --budget --forecast ...'++   See also: Budgeting and Forecasting.+++File: hledger.info,  Node: Cost reporting,  Next: Value reporting,  Prev: Budgeting,  Up: Top++22 Cost reporting+*****************++In some transactions - for example a currency conversion, or a purchase+or sale of stock - one commodity is exchanged for another.  In these+transactions there is a conversion rate, also called the cost (when+buying) or selling price (when selling).  In hledger docs we just say+"cost", for convenience; feel free to mentally translate to "conversion+rate" or "selling price" if helpful.++* Menu:++* Recording costs::+* Reporting at cost::+* Equity conversion postings::+* Inferring equity conversion postings::+* Combining costs and equity conversion postings::+* Requirements for detecting equity conversion postings::+* Infer cost and equity by default ?::+++File: hledger.info,  Node: Recording costs,  Next: Reporting at cost,  Up: Cost reporting++22.1 Recording costs+====================++We'll explore several ways of recording transactions involving costs.+These are also summarised at hledger Cookbook > Cost notation.++   Costs can be recorded explicitly in the journal, using the '@+UNITCOST' or '@@ TOTALCOST' notation described in Journal > Costs:++   *Variant 1*++2022-01-01+  assets:dollars    $-135+  assets:euros       €100 @ $1.35   ; $1.35 per euro (unit cost)++   *Variant 2*++2022-01-01+  assets:dollars    $-135+  assets:euros       €100 @@ $135   ; $135 total cost++   Typically, writing the unit cost (variant 1) is preferable; it can be+more effort, requiring more attention to decimal digits; but it reveals+the per-unit cost basis, and makes stock sales easier.++   Costs can also be left implicit, and hledger will infer the cost that+is consistent with a balanced transaction:++   *Variant 3*++2022-01-01+  assets:dollars    $-135+  assets:euros       €100++   Here, hledger will attach a '@@ €100' cost to the first amount (you+can see it with 'hledger print -x').  This form looks convenient, but+there are downsides:++   * It sacrifices some error checking.  For example, if you+     accidentally wrote €10 instead of €100, hledger would not be able+     to detect the mistake.++   * It is sensitive to the order of postings - if they were reversed, a+     different entry would be inferred and reports would be different.++   * The per-unit cost basis is not easy to read.++   So generally this kind of entry is not recommended.  You can make+sure you have none of these by using '-s' (strict mode), or by running+'hledger check balanced'.+++File: hledger.info,  Node: Reporting at cost,  Next: Equity conversion postings,  Prev: Recording costs,  Up: Cost reporting++22.2 Reporting at cost+======================++Now when you add the '-B'/'--cost' flag to reports ("B" is from Ledger's+-B/-basis/-cost flag), any amounts which have been annotated with costs+will be converted to their cost's commodity (in the report output).  Ie+they will be displayed "at cost" or "at sale price".++   Some things to note:++   * Costs are attached to specific posting amounts in specific+     transactions, and once recorded they do not change.  This contrasts+     with market prices, which are ambient and fluctuating.++   * Conversion to cost is performed before conversion to market value+     (described below).+++File: hledger.info,  Node: Equity conversion postings,  Next: Inferring equity conversion postings,  Prev: Reporting at cost,  Up: Cost reporting++22.3 Equity conversion postings+===============================++There is a problem with the entries above - they are not conventional+Double Entry Bookkeeping (DEB) notation, and because of the "magical"+transformation of one commodity into another, they cause an imbalance in+the Accounting Equation.  This shows up as a non-zero grand total in+balance reports like 'hledger bse'.++   For most hledger users, this doesn't matter in practice and can+safely be ignored !  But if you'd like to learn more, keep reading.++   Conventional DEB uses an extra pair of equity postings to balance the+transaction.  Of course you can do this in hledger as well:++   *Variant 4*++2022-01-01+    assets:dollars      $-135+    assets:euros         €100+    equity:conversion    $135+    equity:conversion   €-100++   Now the transaction is perfectly balanced according to standard DEB,+and 'hledger bse''s total will not be disrupted.++   And, hledger can still infer the cost for cost reporting, but it's+not done by default - you must add the '--infer-costs' flag like so:++$ hledger print --infer-costs+2022-01-01 one hundred euros purchased at $1.35 each+    assets:dollars       $-135 @@ €100+    assets:euros                  €100+    equity:conversion             $135+    equity:conversion            €-100++$ hledger bal --infer-costs -B+               €-100  assets:dollars                                                                                                                                              +                €100  assets:euros                                                                                                                                                +--------------------                                                                                                                                                              +                   0                                                                                                                                                              ++   Here are some downsides of this kind of entry:++   * The per-unit cost basis is not easy to read.++   * Instead of '-B' you must remember to type '-B --infer-costs'.++   * '--infer-costs' works only where hledger can identify the two+     equity:conversion postings and match them up with the two+     non-equity postings.  So writing the journal entry in a particular+     format becomes more important.  More on this below.+++File: hledger.info,  Node: Inferring equity conversion postings,  Next: Combining costs and equity conversion postings,  Prev: Equity conversion postings,  Up: Cost reporting++22.4 Inferring equity conversion postings+=========================================++Can we go in the other direction ?  Yes, if you have transactions+written with the @/@@ cost notation, hledger can infer the missing+equity postings, if you add the '--infer-equity' flag.  Eg:++2022-01-01+  assets:dollars  -$135+  assets:euros     €100 @ $1.35++$ hledger print --infer-equity+2022-01-01+    assets:dollars                    $-135+    assets:euros               €100 @ $1.35+    equity:conversion:$-€:€           €-100+    equity:conversion:$-€:$         $135.00++   The equity account names will be "equity:conversion:A-B:A" and+"equity:conversion:A-B:B" where A is the alphabetically first commodity+symbol.  You can customise the "equity:conversion" part by declaring an+account with the 'V'/'Conversion' account type.+++File: hledger.info,  Node: Combining costs and equity conversion postings,  Next: Requirements for detecting equity conversion postings,  Prev: Inferring equity conversion postings,  Up: Cost reporting++22.5 Combining costs and equity conversion postings+===================================================++Finally, you can use both the @/@@ cost notation and equity postings at+the same time.  This in theory gives the best of all worlds - preserving+the accounting equation, revealing the per-unit cost basis, and+providing more flexibility in how you write the entry:++   *Variant 5*++2022-01-01 one hundred euros purchased at $1.35 each+    assets:dollars      $-135+    equity:conversion    $135+    equity:conversion   €-100+    assets:euros         €100 @ $1.35++   All the other variants above can (usually) be rewritten to this final+form with:++$ hledger print -x --infer-costs --infer-equity++   Downsides:++   * This was added in hledger-1.29 and is still somewhat experimental.++   * The precise format of the journal entry becomes more important.  If+     hledger can't detect and match up the cost and equity postings, it+     will give a transaction balancing error.++   * The add command does not yet accept this kind of entry (#2056).++   * This is the most verbose form.+++File: hledger.info,  Node: Requirements for detecting equity conversion postings,  Next: Infer cost and equity by default ?,  Prev: Combining costs and equity conversion postings,  Up: Cost reporting++22.6 Requirements for detecting equity conversion postings+==========================================================++'--infer-costs' has certain requirements (unlike '--infer-equity', which+always works).  It will infer costs only in transactions with:++   * Two non-equity postings, in different commodities.  Their order is+     significant: the cost will be added to the first of them.++   * Two postings to equity conversion accounts, next to one another,+     which balance the two non-equity postings.  This balancing is+     checked to the same precision (number of decimal places) used in+     the conversion posting's amount.  Equity conversion accounts are:++        * any accounts declared with account type 'V'/'Conversion', or+          their subaccounts+        * otherwise, accounts named 'equity:conversion', 'equity:trade',+          or 'equity:trading', or their subaccounts.++   And multiple such four-posting groups can coexist within a single+transaction.  When '--infer-costs' fails, it does not infer a cost in+that transaction, and does not raise an error (ie, it infers costs where+it can).++   Reading variant 5 journal entries, combining cost notation and equity+postings, has all the same requirements.  When reading such an entry+fails, hledger raises an "unbalanced transaction" error.+++File: hledger.info,  Node: Infer cost and equity by default ?,  Prev: Requirements for detecting equity conversion postings,  Up: Cost reporting++22.7 Infer cost and equity by default ?+=======================================++Should '--infer-costs' and '--infer-equity' be enabled by default ?  Try+using them always, eg with a shell alias:++alias h="hledger --infer-equity --infer-costs"++   and let us know what problems you find.+++File: hledger.info,  Node: Value reporting,  Next: PART 4 COMMANDS,  Prev: Cost reporting,  Up: Top++23 Value reporting+******************++Instead of reporting amounts in their original commodity, hledger can+convert them to cost/sale amount (using the conversion rate recorded in+the transaction), and/or to market value (using some market price on a+certain date).  This is controlled by the '--value=TYPE[,COMMODITY]'+option, which will be described below.  We also provide the simpler '-V'+and '-X COMMODITY' options, and often one of these is all you need:++* Menu:++* -V Value::+* -X Value in specified commodity::+* Valuation date::+* Finding market price::+* --infer-market-prices market prices from transactions::+* Valuation commodity::+* Simple valuation examples::+* --value Flexible valuation::+* More valuation examples::+* Interaction of valuation and queries::+* Effect of valuation on reports::+++File: hledger.info,  Node: -V Value,  Next: -X Value in specified commodity,  Up: Value reporting++23.1 -V: Value+==============++The '-V/--market' flag converts amounts to market value in their default+_valuation commodity_, using the market prices in effect on the+_valuation date(s)_, if any.  More on these in a minute.+++File: hledger.info,  Node: -X Value in specified commodity,  Next: Valuation date,  Prev: -V Value,  Up: Value reporting++23.2 -X: Value in specified commodity+=====================================++The '-X/--exchange=COMM' option is like '-V', except you tell it which+currency you want to convert to, and it tries to convert everything to+that.+++File: hledger.info,  Node: Valuation date,  Next: Finding market price,  Prev: -X Value in specified commodity,  Up: Value reporting++23.3 Valuation date+===================++Market prices can change from day to day.  hledger will use the prices+on a particular valuation date (or on more than one date).  By default+hledger uses "end" dates for valuation.  More specifically:++   * For single period reports (including normal print and register+     reports):+        * If an explicit report end date is specified, that is used+        * Otherwise the latest transaction date or P directive date is+          used (even if it's in the future)++   * For multiperiod reports, each period is valued on its last day.++   This can be customised with the -value option described below, which+can select either "then", "end", "now", or "custom" dates.  (Note, this+has a bug in hledger-ui <=1.31: turning on valuation with the 'V' key+always resets it to "end".)+++File: hledger.info,  Node: Finding market price,  Next: --infer-market-prices market prices from transactions,  Prev: Valuation date,  Up: Value reporting++23.4 Finding market price+=========================++To convert a commodity A to its market value in another commodity B,+hledger looks for a suitable market price (exchange rate) as follows, in+this order of preference:++  1. A _declared market price_ or _inferred market price_: A's latest+     market price in B on or before the valuation date as declared by a+     P directive, or (with the '--infer-market-prices' flag) inferred+     from costs.++  2. A _reverse market price_: the inverse of a declared or inferred+     market price from B to A.++  3. A _forward chain of market prices_: a synthetic price formed by+     combining the shortest chain of "forward" (only 1 above) market+     prices, leading from A to B.++  4. _Any chain of market prices_: a chain of any market prices,+     including both forward and reverse prices (1 and 2 above), leading+     from A to B.++   There is a limit to the length of these price chains; if hledger+reaches that length without finding a complete chain or exhausting all+possibilities, it will give up (with a "gave up" message visible in+'--debug=2' output).  That limit is currently 1000.++   Amounts for which no suitable market price can be found, are not+converted.+++File: hledger.info,  Node: --infer-market-prices market prices from transactions,  Next: Valuation commodity,  Prev: Finding market price,  Up: Value reporting++23.5 -infer-market-prices: market prices from transactions+==========================================================++Normally, market value in hledger is fully controlled by, and requires,+P directives in your journal.  Since adding and updating those can be a+chore, and since transactions usually take place at close to market+value, why not use the recorded costs as additional market prices (as+Ledger does) ?  Adding the '--infer-market-prices' flag to '-V', '-X' or+'--value' enables this.++   So for example, 'hledger bs -V --infer-market-prices' will get market+prices both from P directives and from transactions.  If both occur on+the same day, the P directive takes precedence.++   There is a downside: value reports can sometimes be affected in+confusing/undesired ways by your journal entries.  If this happens to+you, read all of this Value reporting section carefully, and try adding+'--debug' or '--debug=2' to troubleshoot.++   '--infer-market-prices' can infer market prices from:++   * multicommodity transactions with explicit prices ('@'/'@@')++   * multicommodity transactions with implicit prices (no '@', two+     commodities, unbalanced).  (With these, the order of postings+     matters.  'hledger print -x' can be useful for troubleshooting.)++   * multicommodity transactions with equity postings, if cost is+     inferred with '--infer-costs'.++   There is a limitation (bug) currently: when a valuation commodity is+not specified, prices inferred with '--infer-market-prices' do not help+select a default valuation commodity, as 'P' prices would.  So+conversion might not happen because no valuation commodity was detected+('--debug=2' will show this).  To be safe, specify the valuation+commmodity, eg:++   * '-X EUR --infer-market-prices', not '-V --infer-market-prices'+   * '--value=then,EUR --infer-market-prices', not '--value=then+     --infer-market-prices'++   Signed costs and market prices can be confusing.  For reference, here+is the current behaviour, since hledger 1.25.  (If you think it should+work differently, see #1870.)++2022-01-01 Positive Unit prices+    a        A 1+    b        B -1 @ A 1++2022-01-01 Positive Total prices+    a        A 1+    b        B -1 @@ A 1+++2022-01-02 Negative unit prices+    a        A 1+    b        B 1 @ A -1++2022-01-02 Negative total prices+    a        A 1+    b        B 1 @@ A -1+++2022-01-03 Double Negative unit prices+    a        A -1+    b        B -1 @ A -1++2022-01-03 Double Negative total prices+    a        A -1+    b        B -1 @@ A -1++   All of the transactions above are considered balanced (and on each+day, the two transactions are considered equivalent).  Here are the+market prices inferred for B:++$ hledger -f- --infer-market-prices prices+P 2022-01-01 B A 1+P 2022-01-01 B A 1.0+P 2022-01-02 B A -1+P 2022-01-02 B A -1.0+P 2022-01-03 B A -1+P 2022-01-03 B A -1.0+++File: hledger.info,  Node: Valuation commodity,  Next: Simple valuation examples,  Prev: --infer-market-prices market prices from transactions,  Up: Value reporting++23.6 Valuation commodity+========================++*When you specify a valuation commodity ('-X COMM' or '--value+TYPE,COMM'):*+hledger will convert all amounts to COMM, wherever it can find a+suitable market price (including by reversing or chaining prices).++   *When you leave the valuation commodity unspecified ('-V' or '--value+TYPE'):*+For each commodity A, hledger picks a default valuation commodity as+follows, in this order of preference:++  1. The price commodity from the latest P-declared market price for A+     on or before valuation date.++  2. The price commodity from the latest P-declared market price for A+     on any date.  (Allows conversion to proceed when there are inferred+     prices before the valuation date.)++  3. If there are no P directives at all (any commodity or date) and the+     '--infer-market-prices' flag is used: the price commodity from the+     latest transaction-inferred price for A on or before valuation+     date.++   This means:++   * If you have P directives, they determine which commodities '-V'+     will convert, and to what.++   * If you have no P directives, and use the '--infer-market-prices'+     flag, costs determine it.++   Amounts for which no valuation commodity can be found are not+converted.+++File: hledger.info,  Node: Simple valuation examples,  Next: --value Flexible valuation,  Prev: Valuation commodity,  Up: Value reporting++23.7 Simple valuation examples+==============================++Here are some quick examples of '-V':++; one euro is worth this many dollars from nov 1+P 2016/11/01 € $1.10++; purchase some euros on nov 3+2016/11/3+    assets:euros        €100+    assets:checking++; the euro is worth fewer dollars by dec 21+P 2016/12/21 € $1.03++   How many euros do I have ?++$ hledger -f t.j bal -N euros+                €100  assets:euros++   What are they worth at end of nov 3 ?++$ hledger -f t.j bal -N euros -V -e 2016/11/4+             $110.00  assets:euros++   What are they worth after 2016/12/21 ?  (no report end date+specified, defaults to today)++$ hledger -f t.j bal -N euros -V+             $103.00  assets:euros+++File: hledger.info,  Node: --value Flexible valuation,  Next: More valuation examples,  Prev: Simple valuation examples,  Up: Value reporting++23.8 -value: Flexible valuation+===============================++'-V' and '-X' are special cases of the more general '--value' option:++ --value=TYPE[,COMM]  TYPE is then, end, now or YYYY-MM-DD.+                      COMM is an optional commodity symbol.+                      Shows amounts converted to:+                      - default valuation commodity (or COMM) using market prices at posting dates+                      - default valuation commodity (or COMM) using market prices at period end(s)+                      - default valuation commodity (or COMM) using current market prices+                      - default valuation commodity (or COMM) using market prices at some date++   The TYPE part selects cost or value and valuation date:++'--value=then'++     Convert amounts to their value in the default valuation commodity,+     using market prices on each posting's date.+'--value=end'++     Convert amounts to their value in the default valuation commodity,+     using market prices on the last day of the report period (or if+     unspecified, the journal's end date); or in multiperiod reports,+     market prices on the last day of each subperiod.+'--value=now'++     Convert amounts to their value in the default valuation commodity+     using current market prices (as of when report is generated).+'--value=YYYY-MM-DD'++     Convert amounts to their value in the default valuation commodity+     using market prices on this date.++   To select a different valuation commodity, add the optional ',COMM'+part: a comma, then the target commodity's symbol.  Eg:+*'--value=now,EUR'*.  hledger will do its best to convert amounts to+this commodity, deducing market prices as described above.+++File: hledger.info,  Node: More valuation examples,  Next: Interaction of valuation and queries,  Prev: --value Flexible valuation,  Up: Value reporting++23.9 More valuation examples+============================++Here are some examples showing the effect of '--value', as seen with+'print':++P 2000-01-01 A  1 B+P 2000-02-01 A  2 B+P 2000-03-01 A  3 B+P 2000-04-01 A  4 B++2000-01-01+  (a)      1 A @ 5 B++2000-02-01+  (a)      1 A @ 6 B++2000-03-01+  (a)      1 A @ 7 B++   Show the cost of each posting:++$ hledger -f- print --cost+2000-01-01+    (a)             5 B++2000-02-01+    (a)             6 B++2000-03-01+    (a)             7 B++   Show the value as of the last day of the report period (2000-02-29):++$ hledger -f- print --value=end date:2000/01-2000/03+2000-01-01+    (a)             2 B++2000-02-01+    (a)             2 B++   With no report period specified, that shows the value as of the last+day of the journal (2000-03-01):++$ hledger -f- print --value=end+2000-01-01+    (a)             3 B++2000-02-01+    (a)             3 B++2000-03-01+    (a)             3 B++   Show the current value (the 2000-04-01 price is still in effect+today):++$ hledger -f- print --value=now+2000-01-01+    (a)             4 B++2000-02-01+    (a)             4 B++2000-03-01+    (a)             4 B++   Show the value on 2000/01/15:++$ hledger -f- print --value=2000-01-15+2000-01-01+    (a)             1 B++2000-02-01+    (a)             1 B++2000-03-01+    (a)             1 B+++File: hledger.info,  Node: Interaction of valuation and queries,  Next: Effect of valuation on reports,  Prev: More valuation examples,  Up: Value reporting++23.10 Interaction of valuation and queries+==========================================++When matching postings based on queries in the presence of valuation,+the following happens.++  1. The query is separated into two parts:+       1. the currency ('cur:') or amount ('amt:').+       2. all other parts.++  2. The postings are matched to the currency and amount queries based+     on pre-valued amounts.+  3. Valuation is applied to the postings.+  4. The postings are matched to the other parts of the query based on+     post-valued amounts.++   See: 1625+++File: hledger.info,  Node: Effect of valuation on reports,  Prev: Interaction of valuation and queries,  Up: Value reporting++23.11 Effect of valuation on reports+====================================++Here is a reference for how valuation is supposed to affect each part of+hledger's reports (and a glossary).  (It's wide, you'll have to scroll+sideways.)  It may be useful when troubleshooting.  If you find+problems, please report them, ideally with a reproducible example.+Related: #329, #1083.++Report     '-B',        '-V', '-X'   '--value=then'     '--value=end''--value=DATE',+type       '--cost'                                                  '--value=now'+------------------------------------------------------------------------------+*print*+posting    cost         value at     value at posting   value at     value+amounts                 report end   date               report or    at+                        or today                        journal      DATE/today+                                                        end+balance    unchanged    unchanged    unchanged          unchanged    unchanged+assertions/assignments+*register*+starting   cost         value at     valued at day      value at     value+balance                 report or    each historical    report or    at+(-H)                    journal      posting was made   journal      DATE/today+                        end                             end+starting   cost         value at     valued at day      value at     value+balance                 day before   each historical    day before   at+(-H)                    report or    posting was made   report or    DATE/today+with                    journal                         journal+report                  start                           start+interval+posting    cost         value at     value at posting   value at     value+amounts                 report or    date               report or    at+                        journal                         journal      DATE/today+                        end                             end+summary    summarised   value at     sum of postings    value at     value+posting    cost         period       in interval,       period       at+amounts                 ends         valued at          ends         DATE/today+with                                 interval start+report+interval+running    sum/average  sum/average  sum/average of     sum/average  sum/average+total/averageof         of           displayed values   of           of+           displayed    displayed                       displayed    displayed+           values       values                          values       values+*balance+(bs,+bse, cf,+is)*+balance    sums of      value at     value at posting   value at     value+changes    costs        report end   date               report or    at+                        or today                        journal      DATE/today+                        of sums of                      end of       of+                        postings                        sums of      sums+                                                        postings     of+                                                                     postings+budget     like         like         like balance       like         like+amounts    balance      balance      changes            balances     balance+(-budget)  changes      changes                                      changes+grand      sum of       sum of       sum of displayed   sum of       sum of+total      displayed    displayed    valued             displayed    displayed+           values       values                          values       values+*balance+(bs,+bse, cf,+is) with+report+interval*+starting   sums of      value at     sums of values     value at     sums+balances   costs of     report       of postings        report       of+(-H)       postings     start of     before report      start of     postings+           before       sums of      start at           sums of      before+           report       all          respective         all          report+           start        postings     posting dates      postings     start+                        before                          before+                        report                          report+                        start                           start+balance    sums of      same as      sums of values     balance      value+changes    costs of     -value=end   of postings in     change in    at+(bal,      postings                  period at          each         DATE/today+is, bs     in period                 respective         period,      of+-change,                             posting dates      valued at    sums+cf                                                      period       of+-change)                                                ends         postings+end        sums of      same as      sums of values     period end   value+balances   costs of     -value=end   of postings from   balances,    at+(bal -H,   postings                  before period      valued at    DATE/today+is -H,     from                      start to period    period       of+bs, cf)    before                    end at             ends         sums+           report                    respective                      of+           start to                  posting dates                   postings+           period end+budget     like         like         like balance       like         like+amounts    balance      balance      changes/end        balances     balance+(-budget)  changes/end  changes/end  balances                        changes/end+           balances     balances                                     balances+row        sums,        sums,        sums, averages     sums,        sums,+totals,    averages     averages     of displayed       averages     averages+row        of           of           values             of           of+averages   displayed    displayed                       displayed    displayed+(-T, -A)   values       values                          values       values+column     sums of      sums of      sums of            sums of      sums+totals     displayed    displayed    displayed values   displayed    of+           values       values                          values       displayed+                                                                     values+grand      sum,         sum,         sum, average of    sum,         sum,+total,     average of   average of   column totals      average of   average+grand      column       column                          column       of+average    totals       totals                          totals       column+                                                                     totals++   '--cumulative' is omitted to save space, it works like '-H' but with+a zero starting balance.++   *Glossary:*++_cost_++     calculated using price(s) recorded in the transaction(s).+_value_++     market value using available market price declarations, or the+     unchanged amount if no conversion rate can be found.+_report start_++     the first day of the report period specified with -b or -p or+     date:, otherwise today.+_report or journal start_++     the first day of the report period specified with -b or -p or+     date:, otherwise the earliest transaction date in the journal,+     otherwise today.+_report end_++     the last day of the report period specified with -e or -p or date:,+     otherwise today.+_report or journal end_++     the last day of the report period specified with -e or -p or date:,+     otherwise the latest transaction date in the journal, otherwise+     today.+_report interval_++     a flag (-D/-W/-M/-Q/-Y) or period expression that activates the+     report's multi-period mode (whether showing one or many+     subperiods).+++File: hledger.info,  Node: PART 4 COMMANDS,  Next: PART 5 COMMON TASKS,  Prev: Value reporting,  Up: Top++24 PART 4: COMMANDS+*******************++* Menu:++* Commands overview::+* accounts::+* activity::+* add::+* aregister::+* balance::+* balancesheet::+* balancesheetequity::+* cashflow::+* check::+* close::+* codes::+* commodities::+* demo::+* descriptions::+* diff::+* files::+* help::+* import::+* incomestatement::+* notes::+* payees::+* prices::+* print::+* register::+* rewrite::+* roi::+* stats::+* tags::+* test::+++File: hledger.info,  Node: Commands overview,  Next: accounts,  Up: PART 4 COMMANDS++24.1 Commands overview+======================++Here are the built-in commands:++* Menu:++* DATA ENTRY::+* DATA CREATION::+* DATA MANAGEMENT::+* REPORTS FINANCIAL::+* REPORTS VERSATILE::+* REPORTS BASIC::+* HELP::+* ADD-ONS::+++File: hledger.info,  Node: DATA ENTRY,  Next: DATA CREATION,  Up: Commands overview++24.1.1 DATA ENTRY+-----------------++These data entry commands are the only ones which can modify your+journal file.++   * add - add transactions using terminal prompts+   * import - add new transactions from other files, eg CSV files+++File: hledger.info,  Node: DATA CREATION,  Next: DATA MANAGEMENT,  Prev: DATA ENTRY,  Up: Commands overview++24.1.2 DATA CREATION+--------------------++   * close - generate balance-zeroing/restoring transactions+   * rewrite - generate auto postings, like print -auto+++File: hledger.info,  Node: DATA MANAGEMENT,  Next: REPORTS FINANCIAL,  Prev: DATA CREATION,  Up: Commands overview++24.1.3 DATA MANAGEMENT+----------------------++   * check - check for various kinds of error in the data+   * diff - compare account transactions in two journal files+++File: hledger.info,  Node: REPORTS FINANCIAL,  Next: REPORTS VERSATILE,  Prev: DATA MANAGEMENT,  Up: Commands overview++24.1.4 REPORTS, FINANCIAL+-------------------------++   * aregister (areg) - show transactions in a particular account+   * balancesheet (bs) - show assets, liabilities and net worth+   * balancesheetequity (bse) - show assets, liabilities and equity+   * cashflow (cf) - show changes in liquid assets+   * incomestatement (is) - show revenues and expenses+++File: hledger.info,  Node: REPORTS VERSATILE,  Next: REPORTS BASIC,  Prev: REPORTS FINANCIAL,  Up: Commands overview++24.1.5 REPORTS, VERSATILE+-------------------------++   * balance (bal) - show balance changes, end balances, budgets,+     gains..+   * print - show transactions or export journal data+   * register (reg) - show postings in one or more accounts & running+     total+   * roi - show return on investments+++File: hledger.info,  Node: REPORTS BASIC,  Next: HELP,  Prev: REPORTS VERSATILE,  Up: Commands overview++24.1.6 REPORTS, BASIC+---------------------++   * accounts - show account names+   * activity - show bar charts of posting counts per period+   * codes - show transaction codes+   * commodities - show commodity/currency symbols+   * descriptions - show transaction descriptions+   * files - show input file paths+   * notes - show note parts of transaction descriptions+   * payees - show payee parts of transaction descriptions+   * prices - show market prices+   * stats - show journal statistics+   * tags - show tag names+   * test - run self tests+++File: hledger.info,  Node: HELP,  Next: ADD-ONS,  Prev: REPORTS BASIC,  Up: Commands overview++24.1.7 HELP+-----------++   * help - show the hledger manual with info/man/pager+   * demo - show small hledger demos in the terminal+++File: hledger.info,  Node: ADD-ONS,  Prev: HELP,  Up: Commands overview++24.1.8 ADD-ONS+--------------++And here are some typical add-on commands.  Some of these are installed+by the hledger-install script.  If installed, they will appear in+hledger's commands list:++   * ui - run hledger's terminal UI+   * web - run hledger's web UI+   * iadd - add transactions using a TUI (currently hard to build)+   * interest - generate interest transactions+   * stockquotes - download market prices from AlphaVantage+   * Scripts and add-ons - check-fancyassertions, edit, fifo, git, move,+     pijul, plot, and more..++   Next, each command is described in detail, in alphabetical order.+++File: hledger.info,  Node: accounts,  Next: activity,  Prev: Commands overview,  Up: PART 4 COMMANDS++24.2 accounts+=============++Show account names.++   This command lists account names.  By default it shows all known+accounts, either used in transactions or declared with account+directives.++   With query arguments, only matched account names and account names+referenced by matched postings are shown.++   Or it can show just the used accounts ('--used'/'-u'), the declared+accounts ('--declared'/'-d'), the accounts declared but not used+('--unused'), the accounts used but not declared ('--undeclared'), or+the first account matched by an account name pattern, if any ('--find').++   It shows a flat list by default.  With '--tree', it uses indentation+to show the account hierarchy.  In flat mode you can add '--drop N' to+omit the first few account name components.  Account names can be+depth-clipped with 'depth:N' or '--depth N' or '-N'.++   With '--types', it also shows each account's type, if it's known.+(See Declaring accounts > Account types.)++   With '--positions', it also shows the file and line number of each+account's declaration, if any, and the account's overall declaration+order; these may be useful when troubleshooting account display order.++   With '--directives', it adds the 'account' keyword, showing valid+account directives which can be pasted into a journal file.  This is+useful together with '--undeclared' when updating your account+declarations to satisfy 'hledger check accounts'.++   The '--find' flag can be used to look up a single account name, in+the same way that the 'aregister' command does.  It returns the+alphanumerically-first matched account name, or if none can be found, it+fails with a non-zero exit code.++   Examples:++$ hledger accounts+assets:bank:checking+assets:bank:saving+assets:cash+expenses:food+expenses:supplies+income:gifts+income:salary+liabilities:debts++$ hledger accounts --undeclared --directives >> $LEDGER_FILE+$ hledger check accounts+++File: hledger.info,  Node: activity,  Next: add,  Prev: accounts,  Up: PART 4 COMMANDS++24.3 activity+=============++Show an ascii barchart of posting counts per interval.++   The activity command displays an ascii histogram showing transaction+counts by day, week, month or other reporting interval (by day is the+default).  With query arguments, it counts only matched transactions.++   Examples:++$ hledger activity --quarterly+2008-01-01 **+2008-04-01 *******+2008-07-01 +2008-10-01 **+++File: hledger.info,  Node: add,  Next: aregister,  Prev: activity,  Up: PART 4 COMMANDS++24.4 add+========++Prompt for transactions and add them to the journal.  Any arguments will+be used as default inputs for the first N prompts.++   Many hledger users edit their journals directly with a text editor,+or generate them from CSV. For more interactive data entry, there is the+'add' command, which prompts interactively on the console for new+transactions, and appends them to the main journal file (which should be+in journal format).  Existing transactions are not changed.  This is one+of the few hledger commands that writes to the journal file (see also+'import').++   To use it, just run 'hledger add' and follow the prompts.  You can+add as many transactions as you like; when you are finished, enter '.'+or press control-d or control-c to exit.++   Features:++   * add tries to provide useful defaults, using the most similar (by+     description) recent transaction (filtered by the query, if any) as+     a template.+   * You can also set the initial defaults with command line arguments.+   * Readline-style edit keys can be used during data entry.+   * The tab key will auto-complete whenever possible - accounts,+     payees/descriptions, dates ('yesterday', 'today', 'tomorrow').  If+     the input area is empty, it will insert the default value.+   * If the journal defines a default commodity, it will be added to any+     bare numbers entered.+   * A parenthesised transaction code may be entered following a date.+   * Comments and tags may be entered following a description or amount.+   * If you make a mistake, enter '<' at any prompt to go one step+     backward.+   * Input prompts are displayed in a different colour when the terminal+     supports it.++   Example (see https://hledger.org/add.html for a detailed tutorial):++$ hledger add+Adding transactions to journal file /src/hledger/examples/sample.journal+Any command line arguments will be used as defaults.+Use tab key to complete, readline keys to edit, enter to accept defaults.+An optional (CODE) may follow transaction dates.+An optional ; COMMENT may follow descriptions or amounts.+If you make a mistake, enter < at any prompt to go one step backward.+To end a transaction, enter . when prompted.+To quit, enter . at a date prompt or press control-d or control-c.+Date [2015/05/22]: +Description: supermarket+Account 1: expenses:food+Amount  1: $10+Account 2: assets:checking+Amount  2 [$-10.0]: +Account 3 (or . or enter to finish this transaction): .+2015/05/22 supermarket+    expenses:food             $10+    assets:checking        $-10.0++Save this transaction to the journal ? [y]: +Saved.+Starting the next transaction (. or ctrl-D/ctrl-C to quit)+Date [2015/05/22]: <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: PART 4 COMMANDS++24.5 aregister+==============++(areg)++   Show the transactions and running historical balance of a single+account, with each transaction displayed as one line.++   'aregister' shows the overall transactions affecting a particular+account (and any subaccounts).  Each report line represents one+transaction in this account.  Transactions before the report start date+are always included in the running balance ('--historical' mode is+always on).++   This is a more "real world", bank-like view than the 'register'+command (which shows individual postings, possibly from multiple+accounts, not necessarily in historical mode).  As a quick rule of+thumb: - use 'aregister' for reviewing and reconciling real-world+asset/liability accounts - use 'register' for reviewing detailed+revenues/expenses.++   'aregister' requires one argument: the account to report on.  You can+write either the full account name, or a case-insensitive regular+expression which will select the alphabetically first matched account.++   When there are multiple matches, the alphabetically-first choice can+be surprising; eg if you have 'assets:per:checking 1' and+'assets:biz:checking 2' accounts, 'hledger areg checking' would select+'assets:biz:checking 2'.  It's just a convenience to save typing, so if+in doubt, write the full account name, or a distinctive substring that+matches uniquely.++   Transactions involving subaccounts of this account will also be+shown.  'aregister' ignores depth limits, so its final total will always+match a balance report with similar arguments.++   Any additional arguments form a query which will filter the+transactions shown.  Note some queries will disturb the running balance,+causing it to be different from the account's real-world running+balance.++   An example: this shows the transactions and historical running+balance during july, in the first account whose name contains+"checking":++$ hledger areg checking date:jul++   Each 'aregister' line item shows:++   * the transaction's date (or the relevant posting's date if+     different, see below)+   * the names of all the other account(s) involved in this transaction+     (probably abbreviated)+   * the total change to this account's balance from this transaction+   * the account's historical running balance after this transaction.++   Transactions making a net change of zero are not shown by default;+add the '-E/--empty' flag to show them.++   For performance reasons, column widths are chosen based on the first+1000 lines; this means unusually wide values in later lines can cause+visual discontinuities as column widths are adjusted.  If you want to+ensure perfect alignment, at the cost of more time and memory, use the+'--align-all' flag.++   This command also supports the output destination and output format+options.  The output formats supported are 'txt', 'csv', 'tsv', and+'json'.++* Menu:++* aregister and posting dates::+++File: hledger.info,  Node: aregister and posting dates,  Up: aregister++24.5.1 aregister and posting dates+----------------------------------++aregister always shows one line (and date and amount) per transaction.+But sometimes transactions have postings with different dates.  Also,+not all of a transaction's postings may be within the report period.  To+resolve this, aregister shows the earliest of the transaction's date and+posting dates that is in-period, and the sum of the in-period postings.+In other words it will show a combined line item with just the earliest+date, and the running balance will (temporarily, until the transaction's+last posting) be inaccurate.  Use 'register -H' if you need to see the+individual postings.++   There is also a '--txn-dates' flag, which filters strictly by+transaction date, ignoring posting dates.  This too can cause an+inaccurate running balance.+++File: hledger.info,  Node: balance,  Next: balancesheet,  Prev: aregister,  Up: PART 4 COMMANDS++24.6 balance+============++(bal)++   Show accounts and their balances.++   'balance' is one of hledger's oldest and most versatile commands, for+listing account balances, balance changes, values, value changes and+more, during one time period or many.  Generally it shows a table, with+rows representing accounts, and columns representing periods.++   Note there are some higher-level variants of the 'balance' command+with convenient defaults, which can be simpler to use: 'balancesheet',+'balancesheetequity', 'cashflow' and 'incomestatement'.  When you need+more control, then use 'balance'.++* Menu:++* balance features::+* Simple balance report::+* Balance report line format::+* Filtered balance report::+* List or tree mode::+* Depth limiting::+* Dropping top-level accounts::+* Showing declared accounts::+* Sorting by amount::+* Percentages::+* Multi-period balance report::+* Balance change end balance::+* Balance report types::+* Budget report::+* Balance report layout::+* Useful balance reports::+++File: hledger.info,  Node: balance features,  Next: Simple balance report,  Up: balance++24.6.1 balance features+-----------------------++Here's a quick overview of the 'balance' command's features, followed by+more detailed descriptions and examples.  Many of these work with the+higher-level commands as well.++   'balance' can show..++   * accounts as a list ('-l') or a tree ('-t')+   * optionally depth-limited ('-[1-9]')+   * sorted by declaration order and name, or by amount++   ..and their..++   * balance changes (the default)+   * or actual and planned balance changes ('--budget')+   * or value of balance changes ('-V')+   * or change of balance values ('--valuechange')+   * or unrealised capital gain/loss ('--gain')+   * or postings count ('--count')++   ..in..++   * one time period (the whole journal period by default)+   * or multiple periods ('-D', '-W', '-M', '-Q', '-Y', '-p INTERVAL')++   ..either..++   * per period (the default)+   * or accumulated since report start date ('--cumulative')+   * or accumulated since account creation ('--historical/-H')++   ..possibly converted to..++   * cost ('--value=cost[,COMM]'/'--cost'/'-B')+   * or market value, as of transaction dates ('--value=then[,COMM]')+   * or at period ends ('--value=end[,COMM]')+   * or now ('--value=now')+   * or at some other date ('--value=YYYY-MM-DD')++   ..with..++   * totals ('-T'), averages ('-A'), percentages ('-%'), inverted sign+     ('--invert')+   * rows and columns swapped ('--transpose')+   * another field used as account name ('--pivot')+   * custom-formatted line items (single-period reports only)+     ('--format')+   * commodities displayed on the same line or multiple lines+     ('--layout')++   This command supports the output destination and output format+options, with output formats 'txt', 'csv', 'tsv', 'json', and+(multi-period reports only:) 'html'.  In 'txt' output in a+colour-supporting terminal, negative amounts are shown in red.++   The '--related'/'-r' flag shows the balance of the _other_ postings+in the transactions of the postings which would normally be shown.+++File: hledger.info,  Node: Simple balance report,  Next: Balance report line format,  Prev: balance features,  Up: balance++24.6.2 Simple balance report+----------------------------++With no arguments, 'balance' shows a list of all accounts and their+change of balance - ie, the sum of posting amounts, both inflows and+outflows - during the entire period of the journal.  ("Simple" here+means just one column of numbers, covering a single period.  You can+also have multi-period reports, described later.)++   For real-world accounts, these numbers will normally be their end+balance at the end of the journal period; more on this below.++   Accounts are sorted by declaration order if any, and then+alphabetically by account name.  For instance (using+examples/sample.journal):++$ hledger -f examples/sample.journal bal+                  $1  assets:bank:saving+                 $-2  assets:cash+                  $1  expenses:food+                  $1  expenses:supplies+                 $-1  income:gifts+                 $-1  income:salary+                  $1  liabilities:debts+--------------------+                   0  ++   Accounts with a zero balance (and no non-zero subaccounts, in tree+mode - see below) are hidden by default.  Use '-E/--empty' to show them+(revealing 'assets:bank:checking' here):++$ hledger -f examples/sample.journal bal  -E+                   0  assets:bank:checking+                  $1  assets:bank:saving+                 $-2  assets:cash+                  $1  expenses:food+                  $1  expenses:supplies+                 $-1  income:gifts+                 $-1  income:salary+                  $1  liabilities:debts+--------------------+                   0  ++   The total of the amounts displayed is shown as the last line, unless+'-N'/'--no-total' is used.+++File: hledger.info,  Node: Balance report line format,  Next: Filtered balance report,  Prev: Simple balance report,  Up: balance++24.6.3 Balance report line format+---------------------------------++For single-period balance reports displayed in the terminal (only), you+can use '--format FMT' to customise the format and content of each line.+Eg:++$ hledger -f examples/sample.journal balance --format "%20(account) %12(total)"+              assets          $-1+         bank:saving           $1+                cash          $-2+            expenses           $2+                food           $1+            supplies           $1+              income          $-2+               gifts          $-1+              salary          $-1+   liabilities:debts           $1+---------------------------------+                                0++   The FMT format string specifies the formatting applied to each+account/balance pair.  It may contain any suitable text, with data+fields interpolated like so:++   '%[MIN][.MAX](FIELDNAME)'++   * MIN pads with spaces to at least this width (optional)++   * MAX truncates at this width (optional)++   * FIELDNAME must be enclosed in parentheses, and can be one of:++        * 'depth_spacer' - a number of spaces equal to the account's+          depth, or if MIN is specified, MIN * depth spaces.+        * 'account' - the account's name+        * 'total' - the account's balance/posted total, right justified++   Also, FMT can begin with an optional prefix to control how+multi-commodity amounts are rendered:++   * '%_' - render on multiple lines, bottom-aligned (the default)+   * '%^' - render on multiple lines, top-aligned+   * '%,' - render on one line, comma-separated++   There are some quirks.  Eg in one-line mode, '%(depth_spacer)' has no+effect, instead '%(account)' has indentation built in.  Experimentation+may be needed to get pleasing results.++   Some example formats:++   * '%(total)' - the account's total+   * '%-20.20(account)' - the account's name, left justified, padded to+     20 characters and clipped at 20 characters+   * '%,%-50(account) %25(total)' - account name padded to 50+     characters, total padded to 20 characters, with multiple+     commodities rendered on one line+   * '%20(total) %2(depth_spacer)%-(account)' - the default format for+     the single-column balance report+++File: hledger.info,  Node: Filtered balance report,  Next: List or tree mode,  Prev: Balance report line format,  Up: balance++24.6.4 Filtered balance report+------------------------------++You can show fewer accounts, a different time period, totals from+cleared transactions only, etc.  by using query arguments or options to+limit the postings being matched.  Eg:++$ hledger -f examples/sample.journal bal --cleared assets date:200806+                 $-2  assets:cash+--------------------+                 $-2  +++File: hledger.info,  Node: List or tree mode,  Next: Depth limiting,  Prev: Filtered balance report,  Up: balance++24.6.5 List or tree mode+------------------------++By default, or with '-l/--flat', accounts are shown as a flat list with+their full names visible, as in the examples above.++   With '-t/--tree', the account hierarchy is shown, with subaccounts'+"leaf" names indented below their parent:++$ hledger -f examples/sample.journal balance+                 $-1  assets+                  $1    bank:saving+                 $-2    cash+                  $2  expenses+                  $1    food+                  $1    supplies+                 $-2  income+                 $-1    gifts+                 $-1    salary+                  $1  liabilities:debts+--------------------+                   0++   Notes:++   * "Boring" accounts are combined with their subaccount for more+     compact output, unless '--no-elide' is used.  Boring accounts have+     no balance of their own and just one subaccount (eg 'assets:bank'+     and 'liabilities' above).++   * All balances shown are "inclusive", ie including the balances from+     all subaccounts.  Note this means some repetition in the output,+     which requires explanation when sharing reports with+     non-plaintextaccounting-users.  A tree mode report's final total is+     the sum of the top-level balances shown, not of all the balances+     shown.++   * Each group of sibling accounts (ie, under a common parent) is+     sorted separately.+++File: hledger.info,  Node: Depth limiting,  Next: Dropping top-level accounts,  Prev: List or tree mode,  Up: balance++24.6.6 Depth limiting+---------------------++With a 'depth:NUM' query, or '--depth NUM' option, or just '-NUM' (eg:+'-3') balance reports will show accounts only to the specified depth,+hiding the deeper subaccounts.  This can be useful for getting an+overview without too much detail.++   Account balances at the depth limit always include the balances from+any deeper subaccounts (even in list mode).  Eg, limiting to depth 1:++$ hledger -f examples/sample.journal balance -1+                 $-1  assets+                  $2  expenses+                 $-2  income+                  $1  liabilities+--------------------+                   0  +++File: hledger.info,  Node: Dropping top-level accounts,  Next: Showing declared accounts,  Prev: Depth limiting,  Up: balance++24.6.7 Dropping top-level accounts+----------------------------------++You can also hide one or more top-level account name parts, using+'--drop NUM'.  This can be useful for hiding repetitive top-level+account names:++$ hledger -f examples/sample.journal bal expenses --drop 1+                  $1  food+                  $1  supplies+--------------------+                  $2  +++File: hledger.info,  Node: Showing declared accounts,  Next: Sorting by amount,  Prev: Dropping top-level accounts,  Up: balance++24.6.8 Showing declared accounts+--------------------------------++With '--declared', accounts which have been declared with an account+directive will be included in the balance report, even if they have no+transactions.  (Since they will have a zero balance, you will also need+'-E/--empty' to see them.)++   More precisely, _leaf_ declared accounts (with no subaccounts) will+be included, since those are usually the more useful in reports.++   The idea of this is to be able to see a useful "complete" balance+report, even when you don't have transactions in all of your declared+accounts yet.+++File: hledger.info,  Node: Sorting by amount,  Next: Percentages,  Prev: Showing declared accounts,  Up: balance++24.6.9 Sorting by amount+------------------------++With '-S/--sort-amount', accounts with the largest (most positive)+balances are shown first.  Eg: 'hledger bal expenses -MAS' shows your+biggest averaged monthly expenses first.  When more than one commodity+is present, they will be sorted by the alphabetically earliest commodity+first, and then by subsequent commodities (if an amount is missing a+commodity, it is treated as 0).++   Revenues and liability balances are typically negative, however, so+'-S' shows these in reverse order.  To work around this, you can add+'--invert' to flip the signs.  (Or, use one of the higher-level reports,+which flip the sign automatically.  Eg: 'hledger incomestatement -MAS').+++File: hledger.info,  Node: Percentages,  Next: Multi-period balance report,  Prev: Sorting by amount,  Up: balance++24.6.10 Percentages+-------------------++With '-%/--percent', balance reports show each account's value expressed+as a percentage of the (column) total.++   Note it is not useful to calculate percentages if the amounts in a+column have mixed signs.  In this case, make a separate report for each+sign, eg:++$ hledger bal -% amt:`>0`+$ hledger bal -% amt:`<0`++   Similarly, if the amounts in a column have mixed commodities, convert+them to one commodity with '-B', '-V', '-X' or '--value', or make a+separate report for each commodity:++$ hledger bal -% cur:\\$+$ hledger bal -% cur:€+++File: hledger.info,  Node: Multi-period balance report,  Next: Balance change end balance,  Prev: Percentages,  Up: balance++24.6.11 Multi-period balance report+-----------------------------------++With a report interval (set by the '-D/--daily', '-W/--weekly',+'-M/--monthly', '-Q/--quarterly', '-Y/--yearly', or '-p/--period' flag),+'balance' shows a tabular report, with columns representing successive+time periods (and a title):++$ hledger -f examples/sample.journal bal --quarterly income expenses -E+Balance changes in 2008:++                   ||  2008q1  2008q2  2008q3  2008q4 +===================++=================================+ expenses:food     ||       0      $1       0       0 + expenses:supplies ||       0      $1       0       0 + income:gifts      ||       0     $-1       0       0 + income:salary     ||     $-1       0       0       0 +-------------------++---------------------------------+                   ||     $-1      $1       0       0 ++   Notes:++   * The report's start/end dates will be expanded, if necessary, to+     fully encompass the displayed subperiods (so that the first and+     last subperiods have the same duration as the others).+   * Leading and trailing periods (columns) containing all zeroes are+     not shown, unless '-E/--empty' is used.+   * Accounts (rows) containing all zeroes are not shown, unless+     '-E/--empty' is used.+   * Amounts with many commodities are shown in abbreviated form, unless+     '--no-elide' is used.  _(experimental)_+   * Average and/or total columns can be added with the '-A/--average'+     and '-T/--row-total' flags.+   * The '--transpose' flag can be used to exchange rows and columns.+   * The '--pivot FIELD' option causes a different transaction field to+     be used as "account name".  See PIVOTING.++   Multi-period reports with many periods can be too wide for easy+viewing in the terminal.  Here are some ways to handle that:++   * Hide the totals row with '-N/--no-total'+   * Convert to a single currency with '-V'+   * Maximize the terminal window+   * Reduce the terminal's font size+   * View with a pager like less, eg: 'hledger bal -D --color=yes | less+     -RS'+   * Output as CSV and use a CSV viewer like visidata ('hledger bal -D+     -O csv | vd -f csv'), Emacs' csv-mode ('M-x csv-mode, C-c C-a'), or+     a spreadsheet ('hledger bal -D -o a.csv && open a.csv')+   * Output as HTML and view with a browser: 'hledger bal -D -o a.html+     && open a.html'+++File: hledger.info,  Node: Balance change end balance,  Next: Balance report types,  Prev: Multi-period balance report,  Up: balance++24.6.12 Balance change, end balance+-----------------------------------++It's important to be clear on the meaning of the numbers shown in+balance reports.  Here is some terminology we use:++   A *_balance change_* is the net amount added to, or removed from, an+account during some period.++   An *_end balance_* is the amount accumulated in an account as of some+date (and some time, but hledger doesn't store that; assume end of day+in your timezone).  It is the sum of previous balance changes.++   We call it a *_historical end balance_* if it includes all balance+changes since the account was created.  For a real world account, this+means it will match the "historical record", eg the balances reported in+your bank statements or bank web UI. (If they are correct!)++   In general, balance changes are what you want to see when reviewing+revenues and expenses, and historical end balances are what you want to+see when reviewing or reconciling asset, liability and equity accounts.++   'balance' shows balance changes by default.  To see accurate+historical end balances:++  1. Initialise account starting balances with an "opening balances"+     transaction (a transfer from equity to the account), unless the+     journal covers the account's full lifetime.++  2. Include all of of the account's prior postings in the report, by+     not specifying a report start date, or by using the+     '-H/--historical' flag.  ('-H' causes report start date to be+     ignored when summing postings.)+++File: hledger.info,  Node: Balance report types,  Next: Budget report,  Prev: Balance change end balance,  Up: balance++24.6.13 Balance report types+----------------------------++The balance command is quite flexible; here is the full detail on how to+control what it reports.  If the following seems complicated, don't+worry - this is for advanced reporting, and it does take time and+experimentation to get familiar with all the report modes.++   There are three important option groups:++   'hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE]+...'++* Menu:++* Calculation type::+* Accumulation type::+* Valuation type::+* Combining balance report types::+++File: hledger.info,  Node: Calculation type,  Next: Accumulation type,  Up: Balance report types++24.6.13.1 Calculation type+..........................++The basic calculation to perform for each table cell.  It is one of:++   * '--sum' : sum the posting amounts (*default*)+   * '--budget' : sum the amounts, but also show the budget goal amount+     (for each account/period)+   * '--valuechange' : show the change in period-end historical balance+     values (caused by deposits, withdrawals, and/or market price+     fluctuations)+   * '--gain' : show the unrealised capital gain/loss, (the current+     valued balance minus each amount's original cost)+   * '--count' : show the count of postings+++File: hledger.info,  Node: Accumulation type,  Next: Valuation type,  Prev: Calculation type,  Up: Balance report types++24.6.13.2 Accumulation type+...........................++How amounts should accumulate across report periods.  Another way to say+it: which time period's postings should contribute to each cell's+calculation.  It is one of:++   * '--change' : calculate with postings from column start to column+     end, ie "just this column".  Typically used to see+     revenues/expenses.  (*default for balance, incomestatement*)++   * '--cumulative' : calculate with postings from report start to+     column end, ie "previous columns plus this column".  Typically used+     to show changes accumulated since the report's start date.  Not+     often used.++   * '--historical/-H' : calculate with postings from journal start to+     column end, ie "all postings from before report start date until+     this column's end".  Typically used to see historical end balances+     of assets/liabilities/equity.  (*default for balancesheet,+     balancesheetequity, cashflow*)+++File: hledger.info,  Node: Valuation type,  Next: Combining balance report types,  Prev: Accumulation type,  Up: Balance report types++24.6.13.3 Valuation type+........................++Which kind of value or cost conversion should be applied, if any, before+displaying the report.  It is one of:++   * no valuation type : don't convert to cost or value (*default*)+   * '--value=cost[,COMM]' : convert amounts to cost (then optionally to+     some other commodity)+   * '--value=then[,COMM]' : convert amounts to market value on+     transaction dates+   * '--value=end[,COMM]' : convert amounts to market value on period+     end date(s)+     (*default with '--valuechange', '--gain'*)+   * '--value=now[,COMM]' : convert amounts to market value on today's+     date+   * '--value=YYYY-MM-DD[,COMM]' : convert amounts to market value on+     another date++   or one of the equivalent simpler flags:++   * '-B/--cost' : like -value=cost (though, note -cost and -value are+     independent options which can both be used at once)+   * '-V/--market' : like -value=end+   * '-X COMM/--exchange COMM' : like -value=end,COMM++   See Cost reporting and Value reporting for more about these.+++File: hledger.info,  Node: Combining balance report types,  Prev: Valuation type,  Up: Balance report types++24.6.13.4 Combining balance report types+........................................++Most combinations of these options should produce reasonable reports,+but if you find any that seem wrong or misleading, let us know.  The+following restrictions are applied:++   * '--valuechange' implies '--value=end'+   * '--valuechange' makes '--change' the default when used with the+     'balancesheet'/'balancesheetequity' commands+   * '--cumulative' or '--historical' disables '--row-total/-T'++   For reference, here is what the combinations of accumulation and+valuation show:++Valuation:>no valuation    '--value= then'   '--value= end'   '--value=+Accumulation:v                                                YYYY-MM-DD+                                                              /now'+-----------------------------------------------------------------------------+'--change'change in        sum of            period-end       DATE-value+         period            posting-date      value of         of change in+                           market values     change in        period+                           in period         period+'--cumulative'change from  sum of            period-end       DATE-value+         report start to   posting-date      value of         of change+         period end        market values     change from      from report+                           from report       report start     start to+                           start to period   to period end    period end+                           end+'--historicalchange from   sum of            period-end       DATE-value+/-H'     journal start     posting-date      value of         of change+         to period end     market values     change from      from journal+         (historical end   from journal      journal start    start to+         balance)          start to period   to period end    period end+                           end+++File: hledger.info,  Node: Budget report,  Next: Balance report layout,  Prev: Balance report types,  Up: balance++24.6.14 Budget report+---------------------++The '--budget' report type activates extra columns showing any budget+goals for each account and period.  The budget goals are defined by+periodic transactions.  This is useful for comparing planned and actual+income, expenses, time usage, etc.++   For example, you can take average monthly expenses in the common+expense categories to construct a minimal monthly budget:++;; Budget+~ monthly+  income  $2000+  expenses:food    $400+  expenses:bus     $50+  expenses:movies  $30+  assets:bank:checking++;; Two months worth of expenses+2017-11-01+  income  $1950+  expenses:food    $396+  expenses:bus     $49+  expenses:movies  $30+  expenses:supplies  $20+  assets:bank:checking++2017-12-01+  income  $2100+  expenses:food    $412+  expenses:bus     $53+  expenses:gifts   $100+  assets:bank:checking++   You can now see a monthly budget report:++$ hledger balance -M --budget+Budget performance in 2017/11/01-2017/12/31:++                      ||                      Nov                       Dec +======================++====================================================+ assets               || $-2445 [  99% of $-2480]  $-2665 [ 107% of $-2480] + assets:bank          || $-2445 [  99% of $-2480]  $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [  99% of $-2480]  $-2665 [ 107% of $-2480] + expenses             ||   $495 [ 103% of   $480]    $565 [ 118% of   $480] + expenses:bus         ||    $49 [  98% of    $50]     $53 [ 106% of    $50] + expenses:food        ||   $396 [  99% of   $400]    $412 [ 103% of   $400] + expenses:movies      ||    $30 [ 100% of    $30]       0 [   0% of    $30] + income               ||  $1950 [  98% of  $2000]   $2100 [ 105% of  $2000] +----------------------++----------------------------------------------------+                      ||      0 [              0]       0 [              0] ++   This is different from a normal balance report in several ways.+Currently:++   * Accounts with budget goals during the report period, and their+     parents, are shown.+   * Their subaccounts are not shown (regardless of the depth setting).+   * Accounts without budget goals, if any, are aggregated and shown as+     "<unbudgeted>".+   * Amounts are always inclusive (subaccount-including), even in list+     mode.+   * After each actual amount, the corresponding goal amount and+     percentage of goal reached are also shown, in square brackets.++   This means that the numbers displayed will not always add up!  Eg+above, the 'expenses' actual amount includes the gifts and supplies+transactions, but the 'expenses:gifts' and 'expenses:supplies' accounts+are not shown, as they have no budget amounts declared.++   This can be confusing.  When you need to make things clearer, use the+'-E/--empty' flag, which will reveal all accounts including unbudgeted+ones, giving the full picture.  Eg:++$ hledger balance -M --budget --empty+Budget performance in 2017/11/01-2017/12/31:++                      ||                      Nov                       Dec +======================++====================================================+ assets               || $-2445 [  99% of $-2480]  $-2665 [ 107% of $-2480] + assets:bank          || $-2445 [  99% of $-2480]  $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [  99% of $-2480]  $-2665 [ 107% of $-2480] + expenses             ||   $495 [ 103% of   $480]    $565 [ 118% of   $480] + expenses:bus         ||    $49 [  98% of    $50]     $53 [ 106% of    $50] + expenses:food        ||   $396 [  99% of   $400]    $412 [ 103% of   $400] + expenses:gifts       ||      0                      $100                   + expenses:movies      ||    $30 [ 100% of    $30]       0 [   0% of    $30] + expenses:supplies    ||    $20                         0                   + income               ||  $1950 [  98% of  $2000]   $2100 [ 105% of  $2000] +----------------------++----------------------------------------------------+                      ||      0 [              0]       0 [              0] ++   You can roll over unspent budgets to next period with '--cumulative':++$ hledger balance -M --budget --cumulative+Budget performance in 2017/11/01-2017/12/31:++                      ||                      Nov                       Dec +======================++====================================================+ assets               || $-2445 [  99% of $-2480]  $-5110 [ 103% of $-4960] + assets:bank          || $-2445 [  99% of $-2480]  $-5110 [ 103% of $-4960] + assets:bank:checking || $-2445 [  99% of $-2480]  $-5110 [ 103% of $-4960] + expenses             ||   $495 [ 103% of   $480]   $1060 [ 110% of   $960] + expenses:bus         ||    $49 [  98% of    $50]    $102 [ 102% of   $100] + expenses:food        ||   $396 [  99% of   $400]    $808 [ 101% of   $800] + expenses:movies      ||    $30 [ 100% of    $30]     $30 [  50% of    $60] + income               ||  $1950 [  98% of  $2000]   $4050 [ 101% of  $4000] +----------------------++----------------------------------------------------+                      ||      0 [              0]       0 [              0] ++   It's common to limit budgets/budget reports to just expenses++hledger bal -M --budget expenses++   or just revenues and expenses (eg, using account types):++hledger bal -M --budget type:rx++   It's also common to limit or convert them to a single currency+('cur:COMM' or '-X COMM [--infer-market-prices]').  If showing multiple+currencies, '--layout bare' or '--layout tall' can help.++   For more examples and notes, see Budgeting.++* Menu:++* Budget report start date::+* Budgets and subaccounts::+* Selecting budget goals::+* Budget vs forecast::+++File: hledger.info,  Node: Budget report start date,  Next: Budgets and subaccounts,  Up: Budget report++24.6.14.1 Budget report start date+..................................++This might be a bug, but for now: when making budget reports, it's a+good idea to explicitly set the report's start date to the first day of+a reporting period, because a periodic rule like '~ monthly' generates+its transactions on the 1st of each month, and if your journal has no+regular transactions on the 1st, the default report start date could+exclude that budget goal, which can be a little surprising.  Eg here the+default report period is just the day of 2020-01-15:++~ monthly in 2020+  (expenses:food)  $500++2020-01-15+  expenses:food    $400+  assets:checking++$ hledger bal expenses --budget+Budget performance in 2020-01-15:++              || 2020-01-15 +==============++============+ <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++24.6.14.2 Budgets and subaccounts+.................................++You can add budgets to any account in your account hierarchy.  If you+have budgets on both parent account and some of its children, then+budget(s) of the child account(s) would be added to the budget of their+parent, much like account balances behave.++   In the most simple case this means that once you add a budget to any+account, all its parents would have budget as well.++   To illustrate this, consider the following budget:++~ monthly from 2019/01+    expenses:personal             $1,000.00+    expenses:personal:electronics    $100.00+    liabilities++   With this, monthly budget for electronics is defined to be $100 and+budget for personal expenses is an additional $1000, which implicitly+means that budget for both 'expenses:personal' and 'expenses' is $1100.++   Transactions in 'expenses:personal:electronics' will be counted both+towards its $100 budget and $1100 of 'expenses:personal' , and+transactions in any other subaccount of 'expenses:personal' would be+counted towards only towards the budget of 'expenses:personal'.++   For example, let's consider these transactions:++~ monthly from 2019/01+    expenses:personal             $1,000.00+    expenses:personal:electronics    $100.00+    liabilities++2019/01/01 Google home hub+    expenses:personal:electronics          $90.00+    liabilities                           $-90.00++2019/01/02 Phone screen protector+    expenses:personal:electronics:upgrades          $10.00+    liabilities++2019/01/02 Weekly train ticket+    expenses:personal:train tickets       $153.00+    liabilities++2019/01/03 Flowers+    expenses:personal          $30.00+    liabilities++   As you can see, we have transactions in+'expenses:personal:electronics:upgrades' and 'expenses:personal:train+tickets', and since both of these accounts are without explicitly+defined budget, these transactions would be counted towards budgets of+'expenses:personal:electronics' and 'expenses:personal' accordingly:++$ hledger balance --budget -M+Budget performance in 2019/01:++                               ||                           Jan +===============================++===============================+ expenses                      ||  $283.00 [  26% of  $1100.00] + expenses:personal             ||  $283.00 [  26% of  $1100.00] + expenses:personal:electronics ||  $100.00 [ 100% of   $100.00] + liabilities                   || $-283.00 [  26% of $-1100.00] +-------------------------------++-------------------------------+                               ||        0 [                 0] ++   And with '--empty', we can get a better picture of budget allocation+and consumption:++$ hledger balance --budget -M --empty+Budget performance in 2019/01:++                                        ||                           Jan +========================================++===============================+ expenses                               ||  $283.00 [  26% of  $1100.00] + expenses:personal                      ||  $283.00 [  26% of  $1100.00] + expenses:personal:electronics          ||  $100.00 [ 100% of   $100.00] + expenses:personal:electronics:upgrades ||   $10.00                      + expenses:personal:train tickets        ||  $153.00                      + liabilities                            || $-283.00 [  26% of $-1100.00] +----------------------------------------++-------------------------------+                                        ||        0 [                 0] +++File: hledger.info,  Node: Selecting budget goals,  Next: Budget vs forecast,  Prev: Budgets and subaccounts,  Up: Budget report++24.6.14.3 Selecting budget goals+................................++The budget report evaluates periodic transaction rules to generate+special "goal transactions", which generate the goal amounts for each+account in each report subperiod.  When troubleshooting, you can use+'print --forecast' to show these as forecasted transactions:++$ hledger print --forecast=BUDGETREPORTPERIOD tag:generated++   By default, the budget report uses all available periodic transaction+rules to generate goals.  This includes rules with a different report+interval from your report.  Eg if you have daily, weekly and monthly+periodic rules, all of these will contribute to the goals in a monthly+budget report.++   You can select a subset of periodic rules by providing an argument to+the '--budget' flag.  '--budget=DESCPAT' will match all periodic rules+whose description contains DESCPAT, a case-insensitive substring (not a+regular expression or query).  This means you can give your periodic+rules descriptions (remember that two spaces are needed), and then+select from multiple budgets defined in your journal.+++File: hledger.info,  Node: Budget vs forecast,  Prev: Selecting budget goals,  Up: Budget report++24.6.14.4 Budget vs forecast+............................++'hledger --forecast ...' and 'hledger balance --budget ...' are separate+features, though both of them use the periodic transaction rules defined+in the journal, and both of them generate temporary transactions for+reporting purposes ("forecast transactions" and "budget goal+transactions", respectively).  You can use both features at the same+time if you want.  Here are some differences between them, as of hledger+1.29:++   CLI:++   * -forecast is a general hledger option, usable with any command+   * -budget is a 'balance' command option, usable only with that+     command.++   Visibility of generated transactions:++   * forecast transactions are visible in any report, like ordinary+     transactions+   * budget goal transactions are invisible except for the goal amounts+     they produce in -budget reports.++   Periodic transaction rules:++   * -forecast uses all available periodic transaction rules+   * -budget uses all periodic rules ('--budget') or a selected subset+     ('--budget=DESCPAT')++   Period of generated transactions:++   * -forecast generates forecast transactions+        * from after the last regular transaction to the end of the+          report period ('--forecast')+        * or, during a specified period ('--forecast=PERIODEXPR')+        * possibly further restricted by a period specified in the+          periodic transaction rule+        * and always restricted within the bounds of the report period++   * -budget generates budget goal transactions+        * throughout the report period+        * possibly restricted by a period specified in the periodic+          transaction rule.+++File: hledger.info,  Node: Balance report layout,  Next: Useful balance reports,  Prev: Budget report,  Up: balance++24.6.15 Balance report layout+-----------------------------++The '--layout' option affects how balance reports show multi-commodity+amounts and commodity symbols, which can improve readability.  It can+also normalise the data for easy consumption by other programs.  It has+four possible values:++   * '--layout=wide[,WIDTH]': commodities are shown on a single line,+     optionally elided to WIDTH+   * '--layout=tall': each commodity is shown on a separate line+   * '--layout=bare': commodity symbols are in their own column, amounts+     are bare numbers+   * '--layout=tidy': data is normalised to easily-consumed "tidy" form,+     with one row per data value++   Here are the '--layout' modes supported by each output format; note+only CSV output supports all of them:++-      txt   csv   html   json   sql+---------------------------------------+wide   Y     Y     Y+tall   Y     Y     Y+bare   Y     Y     Y+tidy         Y++   Examples:++   * Wide layout.  With many commodities, reports can be very wide:++     $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide+     Balance changes in 2012-01-01..2014-12-31:+     +                       ||                                          2012                                                     2013                                             2014                                                      Total +     ==================++====================================================================================================================================================================================================================+      Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT  70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT  -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT  70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT +     ------------------++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+                       || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT  70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT  -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT  70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT ++   * Limited wide layout.  A width limit reduces the width, but some+     commodities will be hidden:++     $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32+     Balance changes in 2012-01-01..2014-12-31:+     +                       ||                             2012                             2013                   2014                            Total +     ==================++===========================================================================================================================+      Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more..  70.00 GLD, 18.00 ITOT, 3 more..  -11.00 ITOT, 3 more..  70.00 GLD, 17.00 ITOT, 3 more.. +     ------------------++---------------------------------------------------------------------------------------------------------------------------+                       || 10.00 ITOT, 337.18 USD, 2 more..  70.00 GLD, 18.00 ITOT, 3 more..  -11.00 ITOT, 3 more..  70.00 GLD, 17.00 ITOT, 3 more.. ++   * Tall layout.  Each commodity gets a new line (may be different in+     each column), and account names are repeated:++     $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall+     Balance changes in 2012-01-01..2014-12-31:+     +                       ||       2012        2013         2014        Total +     ==================++==================================================+      Assets:US:ETrade || 10.00 ITOT   70.00 GLD  -11.00 ITOT    70.00 GLD +      Assets:US:ETrade || 337.18 USD  18.00 ITOT  4881.44 USD   17.00 ITOT +      Assets:US:ETrade ||  12.00 VEA  -98.12 USD    14.00 VEA  5120.50 USD +      Assets:US:ETrade || 106.00 VHT   10.00 VEA   170.00 VHT    36.00 VEA +      Assets:US:ETrade ||              18.00 VHT                294.00 VHT +     ------------------++--------------------------------------------------+                       || 10.00 ITOT   70.00 GLD  -11.00 ITOT    70.00 GLD +                       || 337.18 USD  18.00 ITOT  4881.44 USD   17.00 ITOT +                       ||  12.00 VEA  -98.12 USD    14.00 VEA  5120.50 USD +                       || 106.00 VHT   10.00 VEA   170.00 VHT    36.00 VEA +                       ||              18.00 VHT                294.00 VHT ++   * Bare layout.  Commodity symbols are kept in one column, each+     commodity gets its own report row, account names are repeated:++     $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare+     Balance changes in 2012-01-01..2014-12-31:+     +                       || Commodity    2012    2013     2014    Total +     ==================++=============================================+      Assets:US:ETrade || GLD             0   70.00        0    70.00 +      Assets:US:ETrade || ITOT        10.00   18.00   -11.00    17.00 +      Assets:US:ETrade || USD        337.18  -98.12  4881.44  5120.50 +      Assets:US:ETrade || VEA         12.00   10.00    14.00    36.00 +      Assets:US:ETrade || VHT        106.00   18.00   170.00   294.00 +     ------------------++---------------------------------------------+                       || GLD             0   70.00        0    70.00 +                       || ITOT        10.00   18.00   -11.00    17.00 +                       || USD        337.18  -98.12  4881.44  5120.50 +                       || VEA         12.00   10.00    14.00    36.00 +                       || VHT        106.00   18.00   170.00   294.00 ++   * Bare layout also affects CSV output, which is useful for producing+     data that is easier to consume, eg for making charts:++     $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare+     "account","commodity","balance"+     "Assets:US:ETrade","GLD","70.00"+     "Assets:US:ETrade","ITOT","17.00"+     "Assets:US:ETrade","USD","5120.50"+     "Assets:US:ETrade","VEA","36.00"+     "Assets:US:ETrade","VHT","294.00"+     "total","GLD","70.00"+     "total","ITOT","17.00"+     "total","USD","5120.50"+     "total","VEA","36.00"+     "total","VHT","294.00"++   * Note: bare layout will sometimes display an extra row for the+     no-symbol commodity, because of zero amounts (hledger treats zeroes+     as commodity-less, usually).  This can break 'hledger-bar'+     confusingly (workaround: add a 'cur:' query to exclude the+     no-symbol row).++   * Tidy layout produces normalised "tidy data", where every variable+     has its own column and each row represents a single data point.+     See+     https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html+     for more.  This is the easiest kind of data for other software to+     consume.  Here's how it looks:++     $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy+     "account","period","start_date","end_date","commodity","value"+     "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0"+     "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00"+     "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18"+     "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00"+     "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00"+     "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00"+     "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00"+     "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12"+     "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00"+     "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00"+     "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0"+     "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00"+     "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44"+     "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00"+     "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00"+++File: hledger.info,  Node: Useful balance reports,  Prev: Balance report layout,  Up: balance++24.6.16 Useful balance reports+------------------------------++Some frequently used 'balance' options/reports are:++   * 'bal -M revenues expenses'+     Show revenues/expenses in each month.  Also available as the+     'incomestatement' command.++   * 'bal -M -H assets liabilities'+     Show historical asset/liability balances at each month end.  Also+     available as the 'balancesheet' command.++   * 'bal -M -H assets liabilities equity'+     Show historical asset/liability/equity balances at each month end.+     Also available as the 'balancesheetequity' command.++   * 'bal -M assets not:receivable'+     Show changes to liquid assets in each month.  Also available as the+     'cashflow' command.++   Also:++   * 'bal -M expenses -2 -SA'+     Show monthly expenses summarised to depth 2 and sorted by average+     amount.++   * 'bal -M --budget expenses'+     Show monthly expenses and budget goals.++   * 'bal -M --valuechange investments'+     Show monthly change in market value of investment assets.++   * 'bal investments --valuechange -D date:lastweek amt:'>1000' -STA+     [--invert]'+     Show top gainers [or losers] last week+++File: hledger.info,  Node: balancesheet,  Next: balancesheetequity,  Prev: balance,  Up: PART 4 COMMANDS++24.7 balancesheet+=================++(bs)++   This command displays a balance sheet, showing historical ending+balances of asset and liability accounts.  (To see equity as well, use+the balancesheetequity command.)  Amounts are shown with normal positive+sign, as in conventional financial statements.++   This report shows accounts declared with the 'Asset', 'Cash' or+'Liability' type (see account types).  Or if no such accounts are+declared, it shows top-level accounts named 'asset' or 'liability' (case+insensitive, plurals allowed) and their subaccounts.++   Example:++$ hledger balancesheet+Balance Sheet++Assets:+                 $-1  assets+                  $1    bank:saving+                 $-2    cash+--------------------+                 $-1++Liabilities:+                  $1  liabilities:debts+--------------------+                  $1++Total:+--------------------+                   0++   This command is a higher-level variant of the 'balance' command, and+supports many of that command's features, such as multi-period reports.+It is similar to 'hledger balance -H assets liabilities', but with+smarter account detection, and liabilities displayed with their sign+flipped.++   This command also supports the output destination and output format+options The output formats supported are 'txt', 'csv', 'tsv', 'html',+and (experimental) 'json'.+++File: hledger.info,  Node: balancesheetequity,  Next: cashflow,  Prev: balancesheet,  Up: PART 4 COMMANDS++24.8 balancesheetequity+=======================++(bse)++   This command displays a balance sheet, showing historical ending+balances of asset, liability and equity accounts.  Amounts are shown+with normal positive sign, as in conventional financial statements.++   This report shows accounts declared with the 'Asset', 'Cash',+'Liability' or 'Equity' type (see account types).  Or if no such+accounts are declared, it shows top-level accounts named 'asset',+'liability' or 'equity' (case insensitive, plurals allowed) and their+subaccounts.++   Example:++$ hledger balancesheetequity+Balance Sheet With Equity++Assets:+                 $-2  assets+                  $1    bank:saving+                 $-3    cash+--------------------+                 $-2++Liabilities:+                  $1  liabilities:debts+--------------------+                  $1++Equity:+          $1  equity:owner+--------------------+          $1++Total:+--------------------+                   0++   This command is a higher-level variant of the 'balance' command, and+supports many of that command's features, such as multi-period reports.+It is similar to 'hledger balance -H assets liabilities equity', but+with smarter account detection, and liabilities/equity displayed with+their sign flipped.++   This command also supports the output destination and output format+options The output formats supported are 'txt', 'csv', 'tsv', 'html',+and (experimental) 'json'.+++File: hledger.info,  Node: cashflow,  Next: check,  Prev: balancesheetequity,  Up: PART 4 COMMANDS++24.9 cashflow+=============++(cf)++   This command displays a cashflow statement, showing the inflows and+outflows affecting "cash" (ie, liquid, easily convertible) assets.+Amounts are shown with normal positive sign, as in conventional+financial statements.++   This report shows accounts declared with the 'Cash' type (see account+types).  Or if no such accounts are declared, it shows accounts++   * under a top-level account named 'asset' (case insensitive, plural+     allowed)+   * whose name contains some variation of 'cash', 'bank', 'checking' or+     'saving'.++   More precisely: all accounts matching this case insensitive regular+expression:++   '^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$)'++   and their subaccounts.++   An example cashflow report:++$ hledger cashflow+Cashflow Statement++Cash flows:+                 $-1  assets+                  $1    bank:saving+                 $-2    cash+--------------------+                 $-1++Total:+--------------------+                 $-1++   This command is a higher-level variant of the 'balance' command, and+supports many of that command's features, such as multi-period reports.+It is similar to 'hledger balance assets not:fixed not:investment+not:receivable', but with smarter account detection.++   This command also supports the output destination and output format+options The output formats supported are 'txt', 'csv', 'tsv', 'html',+and (experimental) 'json'.+++File: hledger.info,  Node: check,  Next: close,  Prev: cashflow,  Up: PART 4 COMMANDS++24.10 check+===========++Check for various kinds of errors in your data.++   hledger provides a number of built-in error checks to help prevent+problems in your data.  Some of these are run automatically; or, you can+use this 'check' command to run them on demand, with no output and a+zero exit code if all is well.  Specify their names (or a prefix) as+argument(s).++   Some examples:++hledger check      # basic checks+hledger check -s   # basic + strict checks+hledger check ordereddates payees  # basic + two other checks++   If you are an Emacs user, you can also configure flycheck-hledger to+run these checks, providing instant feedback as you edit the journal.++   Here are the checks currently available:++* Menu:++* Default checks::+* Strict checks::+* Other checks::+* Custom checks::+* More about specific checks::+++File: hledger.info,  Node: Default checks,  Next: Strict checks,  Up: check++24.10.1 Default checks+----------------------++These checks are run automatically by (almost) all hledger commands:++   * *parseable* - data files are in a supported format, with no syntax+     errors and no invalid include directives.++   * *autobalanced* - all transactions are balanced, after converting to+     cost.  Missing amounts and missing costs are inferred automatically+     where possible.++   * *assertions* - all balance assertions in the journal are passing.+     (This check can be disabled with '-I'/'--ignore-assertions'.)+++File: hledger.info,  Node: Strict checks,  Next: Other checks,  Prev: Default checks,  Up: check++24.10.2 Strict checks+---------------------++These additional checks are run when the '-s'/'--strict' (strict mode)+flag is used.  Or, they can be run by giving their names as arguments to+'check':++   * *balanced* - all transactions are balanced after converting to+     cost, without inferring missing costs.  If conversion costs are+     required, they must be explicit.++   * *accounts* - all account names used by transactions have been+     declared++   * *commodities* - all commodity symbols used have been declared+++File: hledger.info,  Node: Other checks,  Next: Custom checks,  Prev: Strict checks,  Up: check++24.10.3 Other checks+--------------------++These checks can be run only by giving their names as arguments to+'check'.  They are more specialised and not desirable for everyone:++   * *ordereddates* - transactions are ordered by date within each file++   * *payees* - all payees used by transactions have been declared++   * *recentassertions* - all accounts with balance assertions have a+     balance assertion within 7 days of their latest posting++   * *tags* - all tags used by transactions have been declared++   * *uniqueleafnames* - all account leaf names are unique+++File: hledger.info,  Node: Custom checks,  Next: More about specific checks,  Prev: Other checks,  Up: check++24.10.4 Custom checks+---------------------++A few more checks are are available as separate add-on commands, in+https://github.com/simonmichael/hledger/tree/master/bin:++   * *hledger-check-tagfiles* - all tag values containing / (a forward+     slash) exist as file paths++   * *hledger-check-fancyassertions* - more complex balance assertions+     are passing++   You could make similar scripts to perform your own custom checks.+See: Cookbook -> Scripting.+++File: hledger.info,  Node: More about specific checks,  Prev: Custom checks,  Up: check++24.10.5 More about specific checks+----------------------------------++'hledger check recentassertions' will complain if any balance-asserted+account has postings more than 7 days after its latest balance+assertion.  This aims to prevent the situation where you are regularly+updating your journal, but forgetting to check your balances against the+real world, then one day must dig back through months of data to find an+error.  It assumes that adding a balance assertion requires/reminds you+to check the real-world balance.  (That may not be true if you+auto-generate balance assertions from bank data; in that case, I+recommend to import transactions uncleared, and when you manually review+and clear them, also check the latest assertion against the real-world+balance.)+++File: hledger.info,  Node: close,  Next: codes,  Prev: check,  Up: PART 4 COMMANDS++24.11 close+===========++(equity)++   Generate transactions which transfer account balances to and/or from+another account (typically equity).  This can be useful for migrating+balances to a new journal file, or for merging earnings into equity at+end of accounting period.++   By default, it prints a transaction that zeroes out ALE accounts+(asset, liability, equity accounts; this requires account types to be+configured); or if ACCTQUERY is provided, the accounts matched by that.++   _(experimental)_++   This command has four main modes, corresponding to the most common+use cases:++  1. With '--close' (default), it prints a "closing balances"+     transaction that zeroes out ALE (asset, liability, equity) accounts+     by default (this requires account types to be inferred or+     declared); or, the accounts matched by the provided ACCTQUERY+     arguments.++  2. With '--open', it prints an opposite "opening balances" transaction+     that restores those balances from zero.  This is similar to+     Ledger's equity command.++  3. With '--migrate', it prints both the closing and opening+     transactions.  This is the preferred way to migrate balances to a+     new file: run 'hledger close --migrate', add the closing+     transaction at the end of the old file, and add the opening+     transaction at the start of the new file.  The matching+     closing/opening transactions cancel each other out, preserving+     correct balances during multi-file reporting.++  4. With '--retain', it prints a "retain earnings" transaction that+     transfers RX (revenue and expense) balances to 'equity:retained+     earnings'.  Businesses traditionally do this at the end of each+     accounting period; it is less necessary with computer-based+     accounting, but it could still be useful if you want to see the+     accounting equation (A=L+E) satisfied.++   In all modes, the defaults can be overridden:++   * the transaction descriptions can be changed with+     '--close-desc=DESC' and '--open-desc=DESC'+   * the account to transfer to/from can be changed with+     '--close-acct=ACCT' and '--open-acct=ACCT'+   * the accounts to be closed/opened can be changed with 'ACCTQUERY'+     (account query arguments).+   * the closing/opening dates can be changed with '-e DATE' (a report+     end date)++   By default just one destination/source posting will be used, with its+amount left implicit.  With '--x/--explicit', the amount will be shown+explicitly, and if it involves multiple commodities, a separate posting+will be generated for each of them (similar to 'print -x').++   With '--show-costs', any amount costs are shown, with separate+postings for each cost.  This is currently the best way to view+investment lots.  If you have many currency conversion or investment+transactions, it can generate very large journal entries.++   With '--interleaved', each individual transfer is shown with source+and destination postings next to each other.  This could be useful for+troubleshooting.++   The default closing date is yesterday, or the journal's end date,+whichever is later.  You can change this by specifying a report end date+with '-e'.  The last day of the report period will be the closing date,+eg '-e 2024' means "close on 2023-12-31".  The opening date is always+the day after the closing date.++* Menu:++* close and balance assertions::+* Example retain earnings::+* Example migrate balances to a new file::+* Example excluding closing/opening transactions::+++File: hledger.info,  Node: close and balance assertions,  Next: Example retain earnings,  Up: close++24.11.1 close and balance assertions+------------------------------------++Balance assertions will be generated, verifying that the accounts have+been reset to zero (and then restored to their previous balances, if+there is an opening transaction).++   These provide useful error checking, but you can ignore them+temporarily with '-I', or remove them if you prefer.++   You probably should avoid filtering transactions by status or+realness ('-C', '-R', 'status:'), or generating postings ('--auto'),+with this command, since the balance assertions would depend on these.++   Note custom posting dates spanning the file boundary will disrupt the+balance assertions:++2023-12-30 a purchase made in december, cleared in january+    expenses:food          5+    assets:bank:checking  -5  ; date: 2023-01-02++   To solve that you can transfer the money to and from a temporary+account, in effect splitting the multi-day transaction into two+single-day transactions:++; in 2022.journal:+2022-12-30 a purchase made in december, cleared in january+    expenses:food          5+    equity:pending        -5++; in 2023.journal:+2023-01-02 last year's transaction cleared+    equity:pending         5 = 0+    assets:bank:checking  -5+++File: hledger.info,  Node: Example retain earnings,  Next: Example migrate balances to a new file,  Prev: close and balance assertions,  Up: close++24.11.2 Example: retain earnings+--------------------------------++Record 2022's revenues/expenses as retained earnings on 2022-12-31,+appending the generated transaction to the journal:++$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal++   Note 2022's income statement will now show only zeroes, because+revenues and expenses have been moved entirely to equity.  To see them+again, you could exclude the retain transaction:++$ hledger -f 2022.journal is not:desc:'retain earnings'+++File: hledger.info,  Node: Example migrate balances to a new file,  Next: Example excluding closing/opening transactions,  Prev: Example retain earnings,  Up: close++24.11.3 Example: migrate balances to a new file+-----------------------------------------------++Close assets/liabilities/equity on 2022-12-31 and re-open them on+2023-01-01:++$ hledger close --migrate -f 2022.journal -p 2022+# copy/paste the closing transaction to the end of 2022.journal+# copy/paste the opening transaction to the start of 2023.journal++   Now 2022's balance sheet will show only zeroes, indicating a balanced+accounting equation.  (Unless you are using @/@@ notation - in that+case, try adding -infer-equity.)  To see the end-of-year balances again,+you could exclude the closing transaction:++$ hledger -f 2022.journal bs not:desc:'closing balances'+++File: hledger.info,  Node: Example excluding closing/opening transactions,  Prev: Example migrate balances to a new file,  Up: close++24.11.4 Example: excluding closing/opening transactions+-------------------------------------------------------++When combining many files for multi-year reports, the closing/opening+transactions cause some noise in transaction-oriented reports like+'print' and 'register'.  You can exclude them as shown above, but+'not:desc:...' is not ideal as it depends on consistent descriptions;+also you will want to avoid excluding the very first opening+transaction, which could be awkward.  Here is one alternative, using+tags:++   Add 'clopen:' tags to all opening/closing balances transactions+except the first, like this:++; 2021.journal+2021-06-01 first opening balances+...+2021-12-31 closing balances  ; clopen:2022+...++; 2022.journal+2022-01-01 opening balances  ; clopen:2022+...+2022-12-31 closing balances  ; clopen:2023+...++; 2023.journal+2023-01-01 opening balances  ; clopen:2023+...++   Now, assuming a combined journal like:++; all.journal+include 2021.journal+include 2022.journal+include 2023.journal++   The 'clopen:' tag can exclude all but the first opening transaction.+To show a clean multi-year checking register:++$ hledger -f all.journal areg checking not:tag:clopen++   And the year values allow more precision.  To show 2022's year-end+balance sheet:++$ hledger -f all.journal bs -e2023 not:tag:clopen=2023+++File: hledger.info,  Node: codes,  Next: commodities,  Prev: close,  Up: PART 4 COMMANDS++24.12 codes+===========++List the codes seen in transactions, in the order parsed.++   This command prints the value of each transaction's code field, in+the order transactions were parsed.  The transaction code is an optional+value written in parentheses between the date and description, often+used to store a cheque number, order number or similar.++   Transactions aren't required to have a code, and missing or empty+codes will not be shown by default.  With the '-E'/'--empty' flag, they+will be printed as blank lines.++   You can add a query to select a subset of transactions.++   Examples:++2022/1/1 (123) Supermarket   + Food       $5.00+ Checking    ++2022/1/2 (124) Post Office+ Postage    $8.32+ Checking++2022/1/3 Supermarket+ Food      $11.23+ Checking ++2022/1/4 (126) Post Office+ Postage    $3.21+ Checking++$ hledger codes+123+124+126++$ hledger codes -E+123+124++126+++File: hledger.info,  Node: commodities,  Next: demo,  Prev: codes,  Up: PART 4 COMMANDS++24.13 commodities+=================++List all commodity/currency symbols used or declared in the journal.+++File: hledger.info,  Node: demo,  Next: descriptions,  Prev: commodities,  Up: PART 4 COMMANDS++24.14 demo+==========++Play demos of hledger usage in the terminal, if asciinema is installed.++   Run this command with no argument to list the demos.  To play a demo,+write its number or a prefix or substring of its title.  Tips:++   Make your terminal window large enough to see the demo clearly.++   Use the -s/-speed SPEED option to set your preferred playback speed,+eg '-s4' to play at 4x original speed or '-s.5' to play at half speed.+The default speed is 2x.++   Other asciinema options can be added following a double dash, eg '--+-i.1' to limit pauses or '-- -h' to list asciinema's other options.++   During playback, several keys are available: SPACE to pause/unpause,+.  to step forward (while paused), CTRL-c quit.++   Examples:++$ hledger demo               # list available demos+$ hledger demo 1             # play the first demo at default speed (2x)+$ hledger demo install -s4   # play the "install" demo at 4x speed+++File: hledger.info,  Node: descriptions,  Next: diff,  Prev: demo,  Up: PART 4 COMMANDS++24.15 descriptions+==================++List the unique descriptions that appear in transactions.++   This command lists the unique descriptions that appear in+transactions, in alphabetic order.  You can add a query to select a+subset of transactions.++   Example:++$ hledger descriptions+Store Name+Gas Station | Petrol+Person A+++File: hledger.info,  Node: diff,  Next: files,  Prev: descriptions,  Up: PART 4 COMMANDS++24.16 diff+==========++Compares a particular account's transactions in two input files.  It+shows any transactions to this account which are in one file but not in+the other.++   More precisely, for each posting affecting this account in either+file, it looks for a corresponding posting in the other file which posts+the same amount to the same account (ignoring date, description, etc.)+Since postings not transactions are compared, this also works when+multiple bank transactions have been combined into a single journal+entry.++   This is useful eg if you have downloaded an account's transactions+from your bank (eg as CSV data).  When hledger and your bank disagree+about the account balance, you can compare the bank data with your+journal to find out the cause.++   Examples:++$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro +These transactions are in the first file only:++2014/01/01 Opening Balances+    assets:bank:giro              EUR ...+    ...+    equity:opening balances       EUR -...++These transactions are in the second file only:+++File: hledger.info,  Node: files,  Next: help,  Prev: diff,  Up: PART 4 COMMANDS++24.17 files+===========++List all files included in the journal.  With a REGEX argument, only+file names matching the regular expression (case sensitive) are shown.+++File: hledger.info,  Node: help,  Next: import,  Prev: files,  Up: PART 4 COMMANDS++24.18 help+==========++Show the hledger user manual in the terminal, with 'info', 'man', or a+pager.  With a TOPIC argument, open it at that topic if possible.  TOPIC+can be any heading in the manual, or a heading prefix, case insensitive.+Eg: 'commands', 'print', 'forecast', 'journal', 'amount', '"auto+postings"'.++   This command shows the hledger manual built in to your hledger+version.  It can be useful when offline, or when you prefer the terminal+to a web browser, or when the appropriate hledger manual or viewing+tools are not installed on your system.++   By default it chooses the best viewer found in $PATH, trying (in this+order): 'info', 'man', '$PAGER', 'less', 'more'.  You can force the use+of info, man, or a pager with the '-i', '-m', or '-p' flags, If no+viewer can be found, or the command is run non-interactively, it just+prints the manual to stdout.++   If using 'info', note that version 6 or greater is needed for TOPIC+lookup.  If you are on mac you will likely have info 4.8, and should+consider installing a newer version, eg with 'brew install texinfo'+(#1770).++   Examples++$ hledger help --help      # show how the help command works+$ hledger help             # show the hledger manual with info, man or $PAGER+$ hledger help journal     # show the journal topic in the hledger manual+$ hledger help -m journal  # show it with man, even if info is installed+++File: hledger.info,  Node: import,  Next: incomestatement,  Prev: help,  Up: PART 4 COMMANDS++24.19 import+============++Read new transactions added to each FILE provided as arguments since+last run, and add them to the journal.  Or with -dry-run, just print the+transactions that would be added.  Or with -catchup, just mark all of+the FILEs' current transactions as imported, without importing them.++   This command may append new transactions to the main journal file+(which should be in journal format).  Existing transactions are not+changed.  This is one of the few hledger commands that writes to the+journal file (see also 'add').++   Unlike other hledger commands, with 'import' the journal file is an+output file, and will be modified, though only by appending (existing+data will not be changed).  The input files are specified as arguments,+so to import one or more CSV files to your main journal, you will run+'hledger import bank.csv' or perhaps 'hledger import *.csv'.++   Note you can import from any file format, though CSV files are the+most common import source, and these docs focus on that case.++* Menu:++* Deduplication::+* Import testing::+* Importing balance assignments::+* Commodity display styles::+++File: hledger.info,  Node: Deduplication,  Next: Import testing,  Up: import++24.19.1 Deduplication+---------------------++'import' does _time-based deduplication_, to detect only the new+transactions since the last successful import.  (This does not mean+"ignore transactions that look the same", but rather "ignore+transactions that have been seen before".)  This is intended for when+you are periodically importing downloaded data, which may overlap with+previous downloads.  Eg if every week (or every day) you download a+bank's last three months of CSV data, you can safely run 'hledger import+thebank.csv' each time and only new transactions will be imported.++   Since the items being read (CSV records, eg) often do not come with+unique identifiers, hledger detects new transactions by date, assuming+that:++  1. new items always have the newest dates+  2. item dates do not change across reads+  3. and items with the same date remain in the same relative order+     across reads.++   These are often true of CSV files representing transactions, or true+enough so that it works pretty well in practice.  1 is important, but+violations of 2 and 3 amongst the old transactions won't matter (and if+you import often, the new transactions will be few, so less likely to be+the ones affected).++   hledger remembers the latest date processed in each input file by+saving a hidden ".latest.FILE" file in FILE's directory (after a+succesful import).++   Eg when reading 'finance/bank.csv', it will look for and update the+'finance/.latest.bank.csv' state file.  The format is simple: one or+more lines containing the same ISO-format date (YYYY-MM-DD), meaning "I+have processed transactions up to this date, and this many of them on+that date."  Normally you won't see or manipulate these state files+yourself.  But if needed, you can delete them to reset the state (making+all transactions "new"), or you can construct them to "catch up" to a+certain date.++   Note deduplication (and updating of state files) can also be done by+'print --new', but this is less often used.++   Related: CSV > Working with CSV > Deduplicating, importing.+++File: hledger.info,  Node: Import testing,  Next: Importing balance assignments,  Prev: Deduplication,  Up: import++24.19.2 Import testing+----------------------++With '--dry-run', the transactions that will be imported are printed to+the terminal, without updating your journal or state files.  The output+is valid journal format, like the print command, so you can re-parse it.+Eg, to see any importable transactions which CSV rules have not+categorised:++$ hledger import --dry bank.csv | hledger -f- -I print unknown++   or (live updating):++$ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown'++   Note: when importing from multiple files at once, it's currently+possible for some .latest files to be updated successfully, while the+actual import fails because of a problem in one of the files, leaving+them out of sync (and causing some transactions to be missed).  To+prevent this, do a -dry-run first and fix any problems before the real+import.+++File: hledger.info,  Node: Importing balance assignments,  Next: Commodity display styles,  Prev: Import testing,  Up: import++24.19.3 Importing balance assignments+-------------------------------------++Entries added by import will have their posting amounts made explicit+(like 'hledger print -x').  This means that any balance assignments in+imported files must be evaluated; but, imported files don't get to see+the main file's account balances.  As a result, importing entries with+balance assignments (eg from an institution that provides only balances+and not posting amounts) will probably generate incorrect posting+amounts.  To avoid this problem, use print instead of import:++$ hledger print IMPORTFILE [--new] >> $LEDGER_FILE++   (If you think import should leave amounts implicit like print does,+please test it and send a pull request.)+++File: hledger.info,  Node: Commodity display styles,  Prev: Importing balance assignments,  Up: import++24.19.4 Commodity display styles+--------------------------------++Imported amounts will be formatted according to the canonical commodity+styles (declared or inferred) in the main journal file.+++File: hledger.info,  Node: incomestatement,  Next: notes,  Prev: import,  Up: PART 4 COMMANDS++24.20 incomestatement+=====================++(is)++   This command displays an income statement, showing revenues and+expenses during one or more periods.  Amounts are shown with normal+positive sign, as in conventional financial statements.++   This report shows accounts declared with the 'Revenue' or 'Expense'+type (see account types).  Or if no such accounts are declared, it shows+top-level accounts named 'revenue' or 'income' or 'expense' (case+insensitive, plurals allowed) and their subaccounts.++   Example:++$ hledger incomestatement+Income Statement++Revenues:+                 $-2  income+                 $-1    gifts+                 $-1    salary+--------------------+                 $-2++Expenses:+                  $2  expenses+                  $1    food+                  $1    supplies+--------------------+                  $2++Total:+--------------------+                   0++   This command is a higher-level variant of the 'balance' command, and+supports many of that command's features, such as multi-period reports.+It is similar to 'hledger balance '(revenues|income)' expenses', but+with smarter account detection, and revenues/income displayed with their+sign flipped.++   This command also supports the output destination and output format+options The output formats supported are 'txt', 'csv', 'tsv', 'html',+and (experimental) 'json'.+++File: hledger.info,  Node: notes,  Next: payees,  Prev: incomestatement,  Up: PART 4 COMMANDS++24.21 notes+===========++List the unique notes that appear in transactions.++   This command lists the unique notes that appear in transactions, in+alphabetic order.  You can add a query to select a subset of+transactions.  The note is the part of the transaction description after+a | character (or if there is no |, the whole description).++   Example:++$ hledger notes+Petrol+Snacks+++File: hledger.info,  Node: payees,  Next: prices,  Prev: notes,  Up: PART 4 COMMANDS++24.22 payees+============++List the unique payee/payer names that appear in transactions.++   This command lists unique payee/payer names which have been declared+with payee directives (-declared), used in transaction descriptions+(-used), or both (the default).++   The payee/payer is the part of the transaction description before a |+character (or if there is no |, the whole description).++   You can add query arguments to select a subset of transactions.  This+implies -used.++   Example:++$ hledger payees+Store Name+Gas Station+Person A+++File: hledger.info,  Node: prices,  Next: print,  Prev: payees,  Up: PART 4 COMMANDS++24.23 prices+============++Print the market prices declared with P directives.  With+-infer-market-prices, also show any additional prices inferred from+costs.  With -show-reverse, also show additional prices inferred by+reversing known prices.++   Price amounts are always displayed with their full precision, except+for reverse prices which are limited to 8 decimal digits.++   Prices can be filtered by a date:, cur: or amt: query.++   Generally if you run this command with -infer-market-prices+-show-reverse, it will show the same prices used internally to calculate+value reports.  But if in doubt, you can inspect those directly by+running the value report with -debug=2.+++File: hledger.info,  Node: print,  Next: register,  Prev: prices,  Up: PART 4 COMMANDS++24.24 print+===========++Show transaction journal entries, sorted by date.++   The print command displays full journal entries (transactions) from+the journal file, sorted by date (or with '--date2', by secondary date).++   Directives and inter-transaction comments are not shown, currently.+This means the print command is somewhat lossy, and if you are using it+to reformat/regenerate your journal you should take care to also copy+over the directives and inter-transaction comments.++   Eg:++$ hledger print -f examples/sample.journal date:200806+2008/06/01 gift+    assets:bank:checking            $1+    income:gifts                   $-1++2008/06/02 save+    assets:bank:saving              $1+    assets:bank:checking           $-1++2008/06/03 * eat & shop+    expenses:food                $1+    expenses:supplies            $1+    assets:cash                 $-2++* Menu:++* print explicitness::+* print amount style::+* print parseability::+* print other features::+* print output format::+++File: hledger.info,  Node: print explicitness,  Next: print amount style,  Up: print++24.24.1 print explicitness+--------------------------++Normally, whether posting amounts are implicit or explicit is preserved.+For example, when an amount is omitted in the journal, it will not+appear in the output.  Similarly, if a conversion cost is implied but+not written, it will not appear in the output.++   You can use the '-x'/'--explicit' flag to force explicit display of+all amounts and costs.  This can be useful for troubleshooting or for+making your journal more readable and robust against data entry errors.+'-x' is also implied by using any of '-B','-V','-X','--value'.++   The '-x'/'--explicit' flag will cause any postings with a+multi-commodity amount (which can arise when a multi-commodity+transaction has an implicit amount) to be split into multiple+single-commodity postings, keeping the output parseable.+++File: hledger.info,  Node: print amount style,  Next: print parseability,  Prev: print explicitness,  Up: print++24.24.2 print amount style+--------------------------++Amounts are shown right-aligned within each transaction (but not aligned+across all transactions; you can do that with ledger-mode in Emacs).++   Amounts will be (mostly) normalised to their commodity display style:+their symbol placement, decimal mark, and digit group marks will be made+consistent.  By default, decimal digits are shown as they are written in+the journal.++   With the '--round' option, 'print' will try increasingly hard to+display decimal digits according to the commodity display styles:++   * '--round=none' show amounts with original precisions (default)+   * '--round=soft' add/remove decimal zeros in amounts (except costs)+   * '--round=hard' round amounts (except costs), possibly hiding+     significant digits+   * '--round=all' round all amounts and costs++   'soft' is good for non-lossy cleanup, formatting amounts more+consistently where it's safe to do so.++   'hard' and 'all' can cause 'print' to show invalid unbalanced journal+entries; they may be useful eg for stronger cleanup, with manual fixups+when needed.+++File: hledger.info,  Node: print parseability,  Next: print other features,  Prev: print amount style,  Up: print++24.24.3 print parseability+--------------------------++print's output is usually a valid hledger journal, and you can process+it again with a second hledger command.  This can be useful for certain+kinds of search (though the same can be achieved with 'expr:' queries+now):++# Show running total of food expenses paid from cash.+# -f- reads from stdin. -I/--ignore-assertions is sometimes needed.+$ hledger print assets:cash | hledger -f- -I reg expenses:food++   There are some situations where print's output can become+unparseable:++   * Value reporting affects posting amounts but not balance assertion+     or balance assignment amounts, potentially causing those to fail.+   * Auto postings can generate postings with too many missing amounts.+   * Account aliases can generate bad account names.+++File: hledger.info,  Node: print other features,  Next: print output format,  Prev: print parseability,  Up: print++24.24.4 print, other features+-----------------------------++With '-B'/'--cost', amounts with costs are shown converted to cost.++   With '--new', print shows only transactions it has not seen on a+previous run.  This uses the same deduplication system as the 'import'+command.  (See import's docs for details.)++   With '-m DESC'/'--match=DESC', print shows one recent transaction+whose description is most similar to DESC. DESC should contain at least+two characters.  If there is no similar-enough match, no transaction+will be shown and the program exit code will be non-zero.+++File: hledger.info,  Node: print output format,  Prev: print other features,  Up: print++24.24.5 print output format+---------------------------++This command also supports the output destination and output format+options The output formats supported are 'txt', 'beancount', 'csv',+'tsv', 'json' and 'sql'.++   _Experimental:_ The 'beancount' format tries to produce+Beancount-compatible output, as follows:++   * Transaction and postings with unmarked status are converted to+     cleared ('*') status.+   * Transactions' payee and note are backslash-escaped and+     double-quote-escaped and wrapped in double quotes.+   * Transaction tags are copied to Beancount #tag format.+   * Commodity symbols are converted to upper case, and a small number+     of currency symbols like '$' are converted to the corresponding+     currency names.+   * Account name parts are capitalised and unsupported characters are+     replaced with '-'.  If an account name part does not begin with a+     letter, or if the first part is not Assets, Liabilities, Equity,+     Income, or Expenses, an error is raised.  (Use '--alias' options to+     bring your accounts into compliance.)+   * An 'open' directive is generated for each account used, on the+     earliest transaction date.++   Some limitations:++   * Balance assertions are removed.+   * Balance assignments become missing amounts.+   * Virtual and balanced virtual postings become regular postings.+   * Directives are not converted.++   Here's an example of print's CSV output:++$ hledger print -Ocsv+"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment"+"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","",""+"1","2008/01/01","","","","income","","income:salary","-1","$","1","","",""+"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","",""+"2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","",""+"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","",""+"3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","",""+"4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","",""+"4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","",""+"4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","",""+"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""+"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""++   * There is one CSV record per posting, with the parent transaction's+     fields repeated.+   * The "txnidx" (transaction index) field shows which postings belong+     to the same transaction.  (This number might change if transactions+     are reordered within the file, files are parsed/included in a+     different order, etc.)+   * The amount is separated into "commodity" (the symbol) and "amount"+     (numeric quantity) fields.+   * The numeric amount is repeated in either the "credit" or "debit"+     column, for convenience.  (Those names are not accurate in the+     accounting sense; it just puts negative amounts under credit and+     zero or greater amounts under debit.)+++File: hledger.info,  Node: register,  Next: rewrite,  Prev: print,  Up: PART 4 COMMANDS++24.25 register+==============++(reg)++   Show postings and their running total.++   The register command displays matched postings, across all accounts,+in date order, with their running total or running historical balance.+(See also the 'aregister' command, which shows matched transactions in a+specific account.)++   register normally shows line per posting, but note that+multi-commodity amounts will occupy multiple lines (one line per+commodity).++   It is typically used with a query selecting a particular account, to+see that account's activity:++$ hledger register checking+2008/01/01 income               assets:bank:checking            $1           $1+2008/06/01 gift                 assets:bank:checking            $1           $2+2008/06/02 save                 assets:bank:checking           $-1           $1+2008/12/31 pay off              assets:bank:checking           $-1            0++   With '--date2', it shows and sorts by secondary date instead.++   For performance reasons, column widths are chosen based on the first+1000 lines; this means unusually wide values in later lines can cause+visual discontinuities as column widths are adjusted.  If you want to+ensure perfect alignment, at the cost of more time and memory, use the+'--align-all' flag.++   The '--historical'/'-H' flag adds the balance from any undisplayed+prior postings to the running total.  This is useful when you want to+see only recent activity, with a historically accurate running balance:++$ hledger register checking -b 2008/6 --historical+2008/06/01 gift                 assets:bank:checking            $1           $2+2008/06/02 save                 assets:bank:checking           $-1           $1+2008/12/31 pay off              assets:bank:checking           $-1            0++   The '--depth' option limits the amount of sub-account detail+displayed.++   The '--average'/'-A' flag shows the running average posting amount+instead of the running total (so, the final number displayed is the+average for the whole report period).  This flag implies '--empty' (see+below).  It is affected by '--historical'.  It works best when showing+just one account and one commodity.++   The '--related'/'-r' flag shows the _other_ postings in the+transactions of the postings which would normally be shown.++   The '--invert' flag negates all amounts.  For example, it can be used+on an income account where amounts are normally displayed as negative+numbers.  It's also useful to show postings on the checking account+together with the related account:++$ hledger register --related --invert assets:checking++   With a reporting interval, register shows summary postings, one per+interval, aggregating the postings to each account:++$ hledger register --monthly income+2008/01                 income:salary                          $-1          $-1+2008/06                 income:gifts                           $-1          $-2++   Periods with no activity, and summary postings with a zero amount,+are not shown by default; use the '--empty'/'-E' flag to see them:++$ hledger register --monthly income -E+2008/01                 income:salary                          $-1          $-1+2008/02                                                          0          $-1+2008/03                                                          0          $-1+2008/04                                                          0          $-1+2008/05                                                          0          $-1+2008/06                 income:gifts                           $-1          $-2+2008/07                                                          0          $-2+2008/08                                                          0          $-2+2008/09                                                          0          $-2+2008/10                                                          0          $-2+2008/11                                                          0          $-2+2008/12                                                          0          $-2++   Often, you'll want to see just one line per interval.  The '--depth'+option helps with this, causing subaccounts to be aggregated:++$ hledger register --monthly assets --depth 1h+2008/01                 assets                                  $1           $1+2008/06                 assets                                 $-1            0+2008/12                 assets                                 $-1          $-1++   Note when using report intervals, if you specify start/end dates+these will be adjusted outward if necessary to contain a whole number of+intervals.  This ensures that the first and last intervals are full+length and comparable to the others in the report.++   With '-m DESC'/'--match=DESC', register does a fuzzy search for one+recent posting whose description is most similar to DESC. DESC should+contain at least two characters.  If there is no similar-enough match,+no posting will be shown and the program exit code will be non-zero.++* Menu:++* Custom register output::+++File: hledger.info,  Node: Custom register output,  Up: register++24.25.1 Custom register output+------------------------------++register uses the full terminal width by default, except on windows.+You can override this by setting the 'COLUMNS' environment variable (not+a bash shell variable) or by using the '--width'/'-w' option.++   The description and account columns normally share the space equally+(about half of (width - 40) each).  You can adjust this by adding a+description width as part of -width's argument, comma-separated:+'--width W,D' .  Here's a diagram (won't display correctly in -help):++<--------------------------------- width (W) ---------------------------------->+date (10)  description (D)       account (W-41-D)     amount (12)   balance (12)+DDDDDDDDDD dddddddddddddddddddd  aaaaaaaaaaaaaaaaaaa  AAAAAAAAAAAA  AAAAAAAAAAAA++   and some examples:++$ hledger reg                     # use terminal width (or 80 on windows)+$ hledger reg -w 100              # use width 100+$ COLUMNS=100 hledger reg         # set with one-time environment variable+$ export COLUMNS=100; hledger reg # set till session end (or window resize)+$ hledger reg -w 100,40           # set overall width 100, description width 40+$ hledger reg -w $COLUMNS,40      # use terminal width, & description width 40++   This command also supports the output destination and output format+options The output formats supported are 'txt', 'csv', 'tsv', and+(experimental) 'json'.+++File: hledger.info,  Node: rewrite,  Next: roi,  Prev: register,  Up: PART 4 COMMANDS++24.26 rewrite+=============++Print all transactions, rewriting the postings of matched transactions.+For now the only rewrite available is adding new postings, like print+-auto.++   This is a start at a generic rewriter of transaction entries.  It+reads the default journal and prints the transactions, like print, but+adds one or more specified postings to any transactions matching QUERY.+The posting amounts can be fixed, or a multiplier of the existing+transaction's first posting amount.++   Examples:++$ hledger-rewrite.hs ^income --add-posting '(liabilities:tax)  *.33  ; income tax' --add-posting '(reserve:gifts)  $100'+$ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts)  *-1"'+$ hledger-rewrite.hs -f rewrites.hledger++   rewrites.hledger may consist of entries like:++= ^income amt:<0 date:2017+  (liabilities:tax)  *0.33  ; tax on income+  (reserve:grocery)  *0.25  ; reserve 25% for grocery+  (reserve:)  *0.25  ; reserve 25% for grocery++   Note the single quotes to protect the dollar sign from bash, and the+two spaces between account and amount.++   More:++$ hledger rewrite -- [QUERY]        --add-posting "ACCT  AMTEXPR" ...+$ hledger rewrite -- ^income        --add-posting '(liabilities:tax)  *.33'+$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts)  *-1"'+$ hledger rewrite -- ^income        --add-posting '(budget:foreign currency)  *0.25 JPY; diversify'++   Argument for '--add-posting' option is a usual posting of transaction+with an exception for amount specification.  More precisely, you can use+''*'' (star symbol) before the amount to indicate that that this is a+factor for an amount of original matched posting.  If the amount+includes a commodity name, the new posting amount will be in the new+commodity; otherwise, it will be in the matched posting amount's+commodity.++* Menu:++* Re-write rules in a file::+* Diff output format::+* rewrite vs print --auto::+++File: hledger.info,  Node: Re-write rules in a file,  Next: Diff output format,  Up: rewrite++24.26.1 Re-write rules in a file+--------------------------------++During the run this tool will execute so called "Automated Transactions"+found in any journal it process.  I.e instead of specifying this+operations in command line you can put them in a journal file.++$ rewrite-rules.journal++   Make contents look like this:++= ^income+    (liabilities:tax)  *.33++= expenses:gifts+    budget:gifts  *-1+    assets:budget  *1++   Note that ''='' (equality symbol) that is used instead of date in+transactions you usually write.  It indicates the query by which you+want to match the posting to add new ones.++$ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal++   This is something similar to the commands pipeline:++$ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax)  *.33' \+  | hledger rewrite -- -f - expenses:gifts      --add-posting 'budget:gifts  *-1'       \+                                                --add-posting 'assets:budget  *1'       \+  > rewritten-tidy-output.journal++   It is important to understand that relative order of such entries in+journal is important.  You can re-use result of previously added+postings.+++File: hledger.info,  Node: Diff output format,  Next: rewrite vs print --auto,  Prev: Re-write rules in a file,  Up: rewrite++24.26.2 Diff output format+--------------------------++To use this tool for batch modification of your journal files you may+find useful output in form of unified diff.++$ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax)  *.33'++   Output might look like:++--- /tmp/examples/sample.journal++++ /tmp/examples/sample.journal+@@ -18,3 +18,4 @@+ 2008/01/01 income+-    assets:bank:checking  $1++    assets:bank:checking            $1+     income:salary++    (liabilities:tax)                0+@@ -22,3 +23,4 @@+ 2008/06/01 gift+-    assets:bank:checking  $1++    assets:bank:checking            $1+     income:gifts++    (liabilities:tax)                0++   If you'll pass this through 'patch' tool you'll get transactions+containing the posting that matches your query be updated.  Note that+multiple files might be update according to list of input files+specified via '--file' options and 'include' directives inside of these+files.++   Be careful.  Whole transaction being re-formatted in a style of+output from 'hledger print'.++   See also:++   https://github.com/simonmichael/hledger/issues/99+++File: hledger.info,  Node: rewrite vs print --auto,  Prev: Diff output format,  Up: rewrite++24.26.3 rewrite vs. print -auto+-------------------------------++This command predates print -auto, and currently does much the same+thing, but with these differences:++   * with multiple files, rewrite lets rules in any file affect all+     other files.  print -auto uses standard directive scoping; rules+     affect only child files.++   * rewrite's query limits which transactions can be rewritten; all are+     printed.  print -auto's query limits which transactions are+     printed.++   * rewrite applies rules specified on command line or in the journal.+     print -auto applies rules specified in the journal.+++File: hledger.info,  Node: roi,  Next: stats,  Prev: rewrite,  Up: PART 4 COMMANDS++24.27 roi+=========++Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on+your investments.++   At a minimum, you need to supply a query (which could be just an+account name) to select your investment(s) with '--inv', and another+query to identify your profit and loss transactions with '--pnl'.++   If you do not record changes in the value of your investment+manually, or do not require computation of time-weighted return (TWR),+'--pnl' could be an empty query ('--pnl ""' or '--pnl STR' where 'STR'+does not match any of your accounts).++   This command will compute and display the internalized rate of return+(IRR, also known as money-weighted rate of return) and time-weighted+rate of return (TWR) for your investments for the time period requested.+IRR is always annualized due to the way it is computed, but TWR is+reported both as a rate over the chosen reporting period and as an+annual rate.++   Price directives will be taken into account if you supply appropriate+'--cost' or '--value' flags (see VALUATION).++   Note, in some cases this report can fail, for these reasons:++   * Error (NotBracketed): No solution for Internal Rate of Return+     (IRR). Possible causes: IRR is huge (>1000000%), balance of+     investment becomes negative at some point in time.+   * Error (SearchFailed): Failed to find solution for Internal Rate of+     Return (IRR). Either search does not converge to a solution, or+     converges too slowly.++   Examples:++   * Using roi to compute total return of investment in stocks:+     https://github.com/simonmichael/hledger/blob/master/examples/investing/roi-unrealised.ledger++   * Cookbook > Return on Investment: https://hledger.org/roi.html++* Menu:++* Spaces and special characters in --inv and --pnl::+* Semantics of --inv and --pnl::+* IRR and TWR explained::+++File: hledger.info,  Node: Spaces and special characters in --inv and --pnl,  Next: Semantics of --inv and --pnl,  Up: roi++24.27.1 Spaces and special characters in '--inv' and+----------------------------------------------------++'--pnl' Note that '--inv' and '--pnl''s argument is a query, and queries+could have several space-separated terms (see QUERIES).++   To indicate that all search terms form single command-line argument,+you will need to put them in quotes (see Special characters):++$ hledger roi --inv 'term1 term2 term3 ...'++   If any query terms contain spaces themselves, you will need an extra+level of nested quoting, eg:++$ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'"+++File: hledger.info,  Node: Semantics of --inv and --pnl,  Next: IRR and TWR explained,  Prev: Spaces and special characters in --inv and --pnl,  Up: roi++24.27.2 Semantics of '--inv' and '--pnl'+----------------------------------------++Query supplied to '--inv' has to match all transactions that are related+to your investment.  Transactions not matching '--inv' will be ignored.++   In these transactions, ROI will conside postings that match '--inv'+to be "investment postings" and other postings (not matching '--inv')+will be sorted into two categories: "cash flow" and "profit and loss",+as ROI needs to know which part of the investment value is your+contributions and which is due to the return on investment.++   * "Cash flow" is depositing or withdrawing money, buying or selling+     assets, or otherwise converting between your investment commodity+     and any other commodity.  Example:++     2019-01-01 Investing in Snake Oil+       assets:cash          -$100+       investment:snake oil+     +     2020-01-01 Selling my Snake Oil+       assets:cash           $10+       investment:snake oil  = 0++   * "Profit and loss" is change in the value of your investment:++     2019-06-01 Snake Oil falls in value+       investment:snake oil  = $57+       equity:unrealized profit or loss++   All non-investment postings are assumed to be "cash flow", unless+they match '--pnl' query.  Changes in value of your investment due to+"profit and loss" postings will be considered as part of your investment+return.++   Example: if you use '--inv snake --pnl equity:unrealized', then+postings in the example below would be classifed as:++2019-01-01 Snake Oil #1+  assets:cash          -$100   ; cash flow posting+  investment:snake oil         ; investment posting++2019-03-01 Snake Oil #2+  equity:unrealized pnl  -$100 ; profit and loss posting+  snake oil                    ; investment posting++2019-07-01 Snake Oil #3+  equity:unrealized pnl        ; profit and loss posting+  cash          -$100          ; cash flow posting+  snake oil     $50            ; investment posting+++File: hledger.info,  Node: IRR and TWR explained,  Prev: Semantics of --inv and --pnl,  Up: roi++24.27.3 IRR and TWR explained+-----------------------------++"ROI" stands for "return on investment".  Traditionally this was+computed as a difference between current value of investment and its+initial value, expressed in percentage of the initial value.++   However, this approach is only practical in simple cases, where+investments receives no in-flows or out-flows of money, and where rate+of growth is fixed over time.  For more complex scenarios you need+different ways to compute rate of return, and this command implements+two of them: IRR and TWR.++   Internal rate of return, or "IRR" (also called "money-weighted rate+of return") takes into account effects of in-flows and out-flows, and+the time between them.  Investment at a particular fixed interest rate+is going to give you more interest than the same amount invested at the+same interest rate, but made later in time.  If you are withdrawing from+your investment, your future gains would be smaller (in absolute+numbers), and will be a smaller percentage of your initial investment,+so your IRR will be smaller.  And if you are adding to your investment,+you will receive bigger absolute gains, which will be a bigger+percentage of your initial investment, so your IRR will be larger.++   As mentioned before, in-flows and out-flows would be any cash that+you personally put in or withdraw, and for the "roi" command, these are+the postings that match the query in the'--inv' argument and NOT match+the query in the'--pnl' argument.++   If you manually record changes in the value of your investment as+transactions that balance them against "profit and loss" (or "unrealized+gains") account or use price directives, then in order for IRR to+compute the precise effect of your in-flows and out-flows on the rate of+return, you will need to record the value of your investement on or+close to the days when in- or out-flows occur.++   In technical terms, IRR uses the same approach as computation of net+present value, and tries to find a discount rate that makes net present+value of all the cash flows of your investment to add up to zero.  This+could be hard to wrap your head around, especially if you haven't done+discounted cash flow analysis before.  Implementation of IRR in hledger+should produce results that match the '=XIRR' formula in Excel.++   Second way to compute rate of return that 'roi' command implements is+called "time-weighted rate of return" or "TWR". Like IRR, it will+account for the effect of your in-flows and out-flows, but unlike IRR it+will try to compute the true rate of return of the underlying asset,+compensating for the effect that deposits and withdrawas have on the+apparent rate of growth of your investment.++   TWR represents your investment as an imaginary "unit fund" where+in-flows/ out-flows lead to buying or selling "units" of your investment+and changes in its value change the value of "investment unit".  Change+in "unit price" over the reporting period gives you rate of return of+your investment, and make TWR less sensitive than IRR to the effects of+cash in-flows and out-flows.++   References:++   * Explanation of rate of return+   * Explanation of IRR+   * Explanation of TWR+   * IRR vs TWR+   * Examples of computing IRR and TWR and discussion of the limitations+     of both metrics+++File: hledger.info,  Node: stats,  Next: tags,  Prev: roi,  Up: PART 4 COMMANDS++24.28 stats+===========++Show journal and performance statistics.++   The stats command displays summary information for the whole journal,+or a matched part of it.  With a reporting interval, it shows a report+for each report period.++   At the end, it shows (in the terminal) the overall run time and+number of transactions processed per second.  Note these are approximate+and will vary based on machine, current load, data size, hledger+version, haskell lib versions, GHC version..  but they may be of+interest.  The 'stats' command's run time is similar to that of a+single-column balance report.++   Example:++$ hledger stats -f examples/1000x1000x10.journal+Main file                : /Users/simon/src/hledger/examples/1000x1000x10.journal+Included files           : +Transactions span        : 2000-01-01 to 2002-09-27 (1000 days)+Last transaction         : 2002-09-26 (6995 days ago)+Transactions             : 1000 (1.0 per day)+Transactions last 30 days: 0 (0.0 per day)+Transactions last 7 days : 0 (0.0 per day)+Payees/descriptions      : 1000+Accounts                 : 1000 (depth 10)+Commodities              : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z)+Market prices            : 1000 (A)++Run time                 : 0.12 s+Throughput               : 8342 txns/s++   This command supports the -o/-output-file option (but not+-O/-output-format selection).+++File: hledger.info,  Node: tags,  Next: test,  Prev: stats,  Up: PART 4 COMMANDS++24.29 tags+==========++List the tags used in the journal, or their values.++   This command lists the tag names used in the journal, whether on+transactions, postings, or account declarations.++   With a TAGREGEX argument, only tag names matching this regular+expression (case insensitive, infix matched) are shown.++   With QUERY arguments, only transactions and accounts matching this+query are considered.  If the query involves transaction fields (date:,+desc:, amt:, ...), the search is restricted to the matched transactions+and their accounts.++   With the -values flag, the tags' unique non-empty values are listed+instead.  With -E/-empty, blank/empty values are also shown.++   With -parsed, tags or values are shown in the order they were parsed,+with duplicates included.  (Except, tags from account declarations are+always shown first.)++   Tip: remember, accounts also acquire tags from their parents,+postings also acquire tags from their account and transaction,+transactions also acquire tags from their postings.+++File: hledger.info,  Node: test,  Prev: tags,  Up: PART 4 COMMANDS++24.30 test+==========++Run built-in unit tests.++   This command runs the unit tests built in to hledger and hledger-lib,+printing the results on stdout.  If any test fails, the exit code will+be non-zero.++   This is mainly used by hledger developers, but you can also use it to+sanity-check the installed hledger executable on your platform.  All+tests are expected to pass - if you ever see a failure, please report as+a bug!++   This command also accepts tasty test runner options, written after a+- (double hyphen).  Eg to run only the tests in Hledger.Data.Amount,+with ANSI colour codes disabled:++$ hledger test -- -pData.Amount --color=never++   For help on these, see https://github.com/feuerbach/tasty#options+('-- --help' currently doesn't show them).+++File: hledger.info,  Node: PART 5 COMMON TASKS,  Next: BUGS,  Prev: PART 4 COMMANDS,  Up: Top++25 PART 5: COMMON TASKS+***********************++Here are some quick examples of how to do some basic tasks with hledger.++* Menu:++* Getting help::+* Constructing command lines::+* Starting a journal file::+* Setting LEDGER_FILE::+* Setting opening balances::+* Recording transactions::+* Reconciling::+* Reporting::+* Migrating to a new file::+++File: hledger.info,  Node: Getting help,  Next: Constructing command lines,  Up: PART 5 COMMON TASKS++25.1 Getting help+=================++Here's how to list commands and view options and command docs:++$ hledger                # show available commands+$ hledger --help         # show common options+$ hledger CMD --help     # show CMD's options, common options and CMD's documentation++   You can also view your hledger version's manual in several formats by+using the help command.  Eg:++$ hledger help           # show the hledger manual with info, man or $PAGER (best available)+$ hledger help journal   # show the journal topic in the hledger manual+$ hledger help --help    # find out more about the help command++   To view manuals and introductory docs on the web, visit+https://hledger.org.  Chat and mail list support and discussion archives+can be found at https://hledger.org/support.+++File: hledger.info,  Node: Constructing command lines,  Next: Starting a journal file,  Prev: Getting help,  Up: PART 5 COMMON TASKS++25.2 Constructing command lines+===============================++hledger has a flexible command line interface.  We strive to keep it+simple and ergonomic, but if you run into one of the sharp edges+described in OPTIONS, here are some tips that might help:++   * command-specific options must go after the command (it's fine to+     put common options there too: 'hledger CMD OPTS ARGS')+   * running add-on executables directly simplifies command line parsing+     ('hledger-ui OPTS ARGS')+   * enclose "problematic" args in single quotes+   * if needed, also add a backslash to hide regular expression+     metacharacters from the shell+   * to see how a misbehaving command line is being parsed, add+     '--debug=2'.+++File: hledger.info,  Node: Starting a journal file,  Next: Setting LEDGER_FILE,  Prev: Constructing command lines,  Up: PART 5 COMMON TASKS++25.3 Starting a journal file+============================++hledger looks for your accounting data in a journal file,+'$HOME/.hledger.journal' by default:++$ hledger stats+The hledger journal file "/Users/simon/.hledger.journal" was not found.+Please create it first, eg with "hledger add" or a text editor.+Or, specify an existing journal file with -f or LEDGER_FILE.++   You can override this by setting the 'LEDGER_FILE' environment+variable (see below).  It's a good practice to keep this important file+under version control, and to start a new file each year.  So you could+do something like this:++$ mkdir ~/finance+$ cd ~/finance+$ git init+Initialized empty Git repository in /Users/simon/finance/.git/+$ touch 2023.journal+$ echo "export LEDGER_FILE=$HOME/finance/2023.journal" >> ~/.profile+$ source ~/.profile+$ hledger stats+Main file                : /Users/simon/finance/2023.journal+Included files           : +Transactions span        :  to  (0 days)+Last transaction         : none+Transactions             : 0 (0.0 per day)+Transactions last 30 days: 0 (0.0 per day)+Transactions last 7 days : 0 (0.0 per day)+Payees/descriptions      : 0+Accounts                 : 0 (depth 0)+Commodities              : 0 ()+Market prices            : 0 ()+++File: hledger.info,  Node: Setting LEDGER_FILE,  Next: Setting opening balances,  Prev: Starting a journal file,  Up: PART 5 COMMON TASKS++25.4 Setting LEDGER_FILE+========================++How to set 'LEDGER_FILE' permanently depends on your setup:++   On unix and mac, running these commands in the terminal will work for+many people; adapt as needed:++$ echo 'export LEDGER_FILE=~/finance/2023.journal' >> ~/.profile+$ source ~/.profile++   When correctly configured, in a new terminal window 'env | grep+LEDGER_FILE' will show your file, and so will 'hledger files'.++   On mac, this additional step might be helpful for GUI applications+(like Emacs started from the dock): add an entry to+'~/.MacOSX/environment.plist' like++{+  "LEDGER_FILE" : "~/finance/2023.journal"+}++   and then run 'killall Dock' in a terminal window (or restart the+machine).++   On Windows, see https://www.java.com/en/download/help/path.html, or+try running these commands in a powershell window (let us know if it+persists across a reboot, and if you need to be an Administrator):++> CD+> MKDIR finance+> SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal"+++File: hledger.info,  Node: Setting opening balances,  Next: Recording transactions,  Prev: Setting LEDGER_FILE,  Up: PART 5 COMMON TASKS++25.5 Setting opening balances+=============================++Pick a starting date for which you can look up the balances of some+real-world assets (bank accounts, wallet..)  and liabilities (credit+cards..).++   To avoid a lot of data entry, you may want to start with just one or+two accounts, like your checking account or cash wallet; and pick a+recent starting date, like today or the start of the week.  You can+always come back later and add more accounts and older transactions, eg+going back to january 1st.++   Add an opening balances transaction to the journal, declaring the+balances on this date.  Here are two ways to do it:++   * The first way: open the journal in any text editor and save an+     entry like this:++     2023-01-01 * opening balances+         assets:bank:checking                $1000   = $1000+         assets:bank:savings                 $2000   = $2000+         assets:cash                          $100   = $100+         liabilities:creditcard               $-50   = $-50+         equity:opening/closing balances++     These are start-of-day balances, ie whatever was in the account at+     the end of the previous day.++     The * after the date is an optional status flag.  Here it means+     "cleared & confirmed".++     The currency symbols are optional, but usually a good idea as+     you'll be dealing with multiple currencies sooner or later.++     The = amounts are optional balance assertions, providing extra+     error checking.++   * The second way: run 'hledger add' and follow the prompts to record+     a similar transaction:++     $ hledger add+     Adding transactions to journal file /Users/simon/finance/2023.journal+     Any command line arguments will be used as defaults.+     Use tab key to complete, readline keys to edit, enter to accept defaults.+     An optional (CODE) may follow transaction dates.+     An optional ; COMMENT may follow descriptions or amounts.+     If you make a mistake, enter < at any prompt to go one step backward.+     To end a transaction, enter . when prompted.+     To quit, enter . at a date prompt or press control-d or control-c.+     Date [2023-02-07]: 2023-01-01+     Description: * opening balances+     Account 1: assets:bank:checking+     Amount  1: $1000+     Account 2: assets:bank:savings+     Amount  2 [$-1000]: $2000+     Account 3: assets:cash+     Amount  3 [$-3000]: $100+     Account 4: liabilities:creditcard+     Amount  4 [$-3100]: $-50+     Account 5: equity:opening/closing balances+     Amount  5 [$-3050]: +     Account 6 (or . or enter to finish this transaction): .+     2023-01-01 * opening balances+         assets:bank:checking                      $1000+         assets:bank:savings                       $2000+         assets:cash                                $100+         liabilities:creditcard                     $-50+         equity:opening/closing balances          $-3050+     +     Save this transaction to the journal ? [y]: +     Saved.+     Starting the next transaction (. or ctrl-D/ctrl-C to quit)+     Date [2023-01-01]: .++   If you're using version control, this could be a good time to commit+the journal.  Eg:++$ git commit -m 'initial balances' 2023.journal+++File: hledger.info,  Node: Recording transactions,  Next: Reconciling,  Prev: Setting opening balances,  Up: PART 5 COMMON TASKS++25.6 Recording transactions+===========================++As you spend or receive money, you can record these transactions using+one of the methods above (text editor, hledger add) or by using the+hledger-iadd or hledger-web add-ons, or by using the import command to+convert CSV data downloaded from your bank.++   Here are some simple transactions, see the hledger_journal(5) manual+and hledger.org for more ideas:++2023/1/10 * gift received+  assets:cash   $20+  income:gifts++2023.1.12 * farmers market+  expenses:food    $13+  assets:cash++2023-01-15 paycheck+  income:salary+  assets:bank:checking    $1000+++File: hledger.info,  Node: Reconciling,  Next: Reporting,  Prev: Recording transactions,  Up: PART 5 COMMON TASKS++25.7 Reconciling+================++Periodically you should reconcile - compare your hledger-reported+balances against external sources of truth, like bank statements or your+bank's website - to be sure that your ledger accurately represents the+real-world balances (and, that the real-world institutions have not made+a mistake!).  This gets easy and fast with (1) practice and (2)+frequency.  If you do it daily, it can take 2-10 minutes.  If you let it+pile up, expect it to take longer as you hunt down errors and+discrepancies.++   A typical workflow:++  1. Reconcile cash.  Count what's in your wallet.  Compare with what+     hledger reports ('hledger bal cash').  If they are different, try+     to remember the missing transaction, or look for the error in the+     already-recorded transactions.  A register report can be helpful+     ('hledger reg cash').  If you can't find the error, add an+     adjustment transaction.  Eg if you have $105 after the above, and+     can't explain the missing $2, it could be:++     2023-01-16 * adjust cash+         assets:cash    $-2 = $105+         expenses:misc++  2. Reconcile checking.  Log in to your bank's website.  Compare+     today's (cleared) balance with hledger's cleared balance ('hledger+     bal checking -C').  If they are different, track down the error or+     record the missing transaction(s) or add an adjustment transaction,+     similar to the above.  Unlike the cash case, you can usually+     compare the transaction history and running balance from your bank+     with the one reported by 'hledger reg checking -C'.  This will be+     easier if you generally record transaction dates quite similar to+     your bank's clearing dates.++  3. Repeat for other asset/liability accounts.++   Tip: instead of the register command, use hledger-ui to see a+live-updating register while you edit the journal: 'hledger-ui --watch+--register checking -C'++   After reconciling, it could be a good time to mark the reconciled+transactions' status as "cleared and confirmed", if you want to track+that, by adding the '*' marker.  Eg in the paycheck transaction above,+insert '*' between '2023-01-15' and 'paycheck'++   If you're using version control, this can be another good time to+commit:++$ git commit -m 'txns' 2023.journal+++File: hledger.info,  Node: Reporting,  Next: Migrating to a new file,  Prev: Reconciling,  Up: PART 5 COMMON TASKS++25.8 Reporting+==============++Here are some basic reports.++   Show all transactions:++$ hledger print+2023-01-01 * opening balances+    assets:bank:checking                      $1000+    assets:bank:savings                       $2000+    assets:cash                                $100+    liabilities:creditcard                     $-50+    equity:opening/closing balances          $-3050++2023-01-10 * gift received+    assets:cash              $20+    income:gifts++2023-01-12 * farmers market+    expenses:food             $13+    assets:cash++2023-01-15 * paycheck+    income:salary+    assets:bank:checking           $1000++2023-01-16 * adjust cash+    assets:cash               $-2 = $105+    expenses:misc++   Show account names, and their hierarchy:++$ hledger accounts --tree+assets+  bank+    checking+    savings+  cash+equity+  opening/closing balances+expenses+  food+  misc+income+  gifts+  salary+liabilities+  creditcard++   Show all account totals:++$ hledger balance+               $4105  assets+               $4000    bank+               $2000      checking+               $2000      savings+                $105    cash+              $-3050  equity:opening/closing balances+                 $15  expenses+                 $13    food+                  $2    misc+              $-1020  income+                $-20    gifts+              $-1000    salary+                $-50  liabilities:creditcard+--------------------+                   0++   Show only asset and liability balances, as a flat list, limited to+depth 2:++$ hledger bal assets liabilities -2+               $4000  assets:bank+                $105  assets:cash+                $-50  liabilities:creditcard+--------------------+               $4055++   Show the same thing without negative numbers, formatted as a simple+balance sheet:++$ hledger bs -2+Balance Sheet 2023-01-16++                        || 2023-01-16 +========================++============+ Assets                 ||            +------------------------++------------+ assets:bank            ||      $4000 + assets:cash            ||       $105 +------------------------++------------+                        ||      $4105 +========================++============+ Liabilities            ||            +------------------------++------------+ liabilities:creditcard ||        $50 +------------------------++------------+                        ||        $50 +========================++============+ Net:                   ||      $4055 ++   The final total is your "net worth" on the end date.  (Or use 'bse'+for a full balance sheet with equity.)++   Show income and expense totals, formatted as an income statement:++hledger is +Income Statement 2023-01-01-2023-01-16++               || 2023-01-01-2023-01-16 +===============++=======================+ Revenues      ||                       +---------------++-----------------------+ income:gifts  ||                   $20 + income:salary ||                 $1000 +---------------++-----------------------+               ||                 $1020 +===============++=======================+ Expenses      ||                       +---------------++-----------------------+ expenses:food ||                   $13 + expenses:misc ||                    $2 +---------------++-----------------------+               ||                   $15 +===============++=======================+ Net:          ||                 $1005 ++   The final total is your net income during this period.++   Show transactions affecting your wallet, with running total:++$ hledger register cash+2023-01-01 opening balances     assets:cash                   $100          $100+2023-01-10 gift received        assets:cash                    $20          $120+2023-01-12 farmers market       assets:cash                   $-13          $107+2023-01-16 adjust cash          assets:cash                    $-2          $105++   Show weekly posting counts as a bar chart:++$ hledger activity -W+2019-12-30 *****+2023-01-06 ****+2023-01-13 ****+++File: hledger.info,  Node: Migrating to a new file,  Prev: Reporting,  Up: PART 5 COMMON TASKS++25.9 Migrating to a new file+============================++At the end of the year, you may want to continue your journal in a new+file, so that old transactions don't slow down or clutter your reports,+and to help ensure the integrity of your accounting history.  See the+close command.++   If using version control, don't forget to 'git add' the new file.+++File: hledger.info,  Node: BUGS,  Prev: PART 5 COMMON TASKS,  Up: Top++26 BUGS+*******++We welcome bug reports in the hledger issue tracker (shortcut:+http://bugs.hledger.org), or on the #hledger chat or hledger mail list+(https://hledger.org/support).++   Some known issues and limitations:++   The need to precede add-on command options with '--' when invoked+from hledger is awkward.  (See Command options, Constructing command+lines.)++   A UTF-8-aware system locale must be configured to work with non-ascii+data.  (See Unicode characters, Troubleshooting.)++   On Microsoft Windows, depending whether you are running in a CMD+window or a Cygwin/MSYS/Mintty window and how you installed hledger,+non-ascii characters and colours may not be supported, and the tab key+may not be supported by 'hledger add'.  (Running in a WSL window should+resolve these.)++   When processing large data files, hledger uses more memory than+Ledger.++* Menu:++* Troubleshooting::+++File: hledger.info,  Node: Troubleshooting,  Up: BUGS++26.1 Troubleshooting+====================++Here are some common issues you might encounter when you run hledger,+and how to resolve them (and remember also you can usually get quick+Support):++   *PATH issues: I get an error like "No command 'hledger' found"*+Depending how you installed hledger, the executables may not be in your+shell's PATH. Eg on unix systems, stack installs hledger in+'~/.local/bin' and cabal installs it in '~/.cabal/bin'.  You may need to+add one of these directories to your shell's PATH, and/or open a new+terminal window.++   *LEDGER_FILE issues: I configured LEDGER_FILE but hledger is not+using it*++   * 'LEDGER_FILE' should be a real environment variable, not just a+     shell variable.  Eg on unix, the command 'env | grep LEDGER_FILE'+     should show it.  You may need to use 'export' (see+     https://stackoverflow.com/a/7411509).+   * You may need to force your shell to see the new configuration.  A+     simple way is to close your terminal window and open a new one.++   *LANG issues: I get errors like "Illegal byte sequence" or "Invalid+or incomplete multibyte or wide character" or "commitAndReleaseBuffer:+invalid argument (invalid character)"*+Programs compiled with GHC (hledger, haskell build tools, etc.)  need+the system locale to be UTF-8-aware, or they will fail when they+encounter non-ascii characters.  To fix it, set the LANG environment+variable to a locale which supports UTF-8 and which is installed on your+system.++   On unix, 'locale -a' lists the installed locales.  Look for one which+mentions 'utf8', 'UTF-8' or similar.  Some examples: 'C.UTF-8',+'en_US.utf-8', 'fr_FR.utf8'.  If necessary, use your system package+manager to install one.  Then select it by setting the 'LANG'+environment variable.  Note, exact spelling and capitalisation of the+locale name may be important: Here's one common way to configure this+permanently for your shell:++$ echo "export LANG=en_US.utf8" >>~/.profile+# close and re-open terminal window++   If you are using Nix (not NixOS) for GHC and Hledger, you might need+to set the 'LOCALE_ARCHIVE' variable:++$ echo "export LOCALE_ARCHIVE=${glibcLocales}/lib/locale/locale-archive" >>~/.profile+# close and re-open terminal window++   *COMPATIBILITY ISSUES: hledger gives an error with my Ledger file*+Not all of Ledger's journal file syntax or feature set is supported.+See hledger and Ledger for full details.+++Tag Table:+Node: Top210+Node: PART 1 USER INTERFACE3822+Ref: #part-1-user-interface3961+Node: Input3961+Ref: #input4071+Node: Data formats5020+Ref: #data-formats5133+Node: Standard input6495+Ref: #standard-input6635+Node: Multiple files6862+Ref: #multiple-files7001+Node: Strict mode7599+Ref: #strict-mode7709+Node: Commands8433+Ref: #commands8535+Node: Add-on commands9602+Ref: #add-on-commands9704+Node: Options10820+Ref: #options10932+Node: General help options11260+Ref: #general-help-options11406+Node: General input options11688+Ref: #general-input-options11870+Node: General reporting options12572+Ref: #general-reporting-options12733+Node: Command line tips16123+Ref: #command-line-tips16253+Node: Option repetition16512+Ref: #option-repetition16656+Node: Special characters16760+Ref: #special-characters16933+Node: Single escaping shell metacharacters17096+Ref: #single-escaping-shell-metacharacters17337+Node: Double escaping regular expression metacharacters17940+Ref: #double-escaping-regular-expression-metacharacters18251+Node: Triple escaping for add-on commands18777+Ref: #triple-escaping-for-add-on-commands19037+Node: Less escaping19681+Ref: #less-escaping19835+Node: Unicode characters20159+Ref: #unicode-characters20334+Node: Regular expressions21746+Ref: #regular-expressions21919+Node: hledger's regular expressions25015+Ref: #hledgers-regular-expressions25174+Node: Argument files26560+Ref: #argument-files26696+Node: Output27193+Ref: #output27305+Node: Output destination27432+Ref: #output-destination27563+Node: Output format27988+Ref: #output-format28134+Node: CSV output29731+Ref: #csv-output29847+Node: HTML output29950+Ref: #html-output30088+Node: JSON output30182+Ref: #json-output30320+Node: SQL output31242+Ref: #sql-output31358+Node: Commodity styles32093+Ref: #commodity-styles32233+Node: Colour32832+Ref: #colour32950+Node: Box-drawing33354+Ref: #box-drawing33472+Node: Paging33762+Ref: #paging33876+Node: Debug output34829+Ref: #debug-output34935+Node: Environment35598+Ref: #environment35722+Node: PART 2 DATA FORMATS36266+Ref: #part-2-data-formats36409+Node: Journal36409+Ref: #journal36518+Node: Journal cheatsheet37175+Ref: #journal-cheatsheet37314+Node: About journal format41299+Ref: #about-journal-format41459+Node: Comments43075+Ref: #comments43205+Node: Transactions44021+Ref: #transactions44144+Node: Dates45158+Ref: #dates45265+Node: Simple dates45310+Ref: #simple-dates45426+Node: Posting dates45926+Ref: #posting-dates46044+Node: Status47013+Ref: #status47114+Node: Code48822+Ref: #code48925+Node: Description49157+Ref: #description49288+Node: Payee and note49608+Ref: #payee-and-note49714+Node: Transaction comments50049+Ref: #transaction-comments50202+Node: Postings50565+Ref: #postings50698+Node: Account names51693+Ref: #account-names51823+Node: Amounts53497+Ref: #amounts53612+Node: Decimal marks digit group marks54597+Ref: #decimal-marks-digit-group-marks54772+Node: Commodity55631+Ref: #commodity55818+Node: Directives influencing number parsing and display56770+Ref: #directives-influencing-number-parsing-and-display57029+Node: Commodity display style57481+Ref: #commodity-display-style57687+Node: Rounding59097+Ref: #rounding59215+Node: Costs59665+Ref: #costs59781+Node: Other cost/lot notations61977+Ref: #other-costlot-notations62109+Node: Balance assertions64698+Ref: #balance-assertions64849+Node: Assertions and ordering65932+Ref: #assertions-and-ordering66121+Node: Assertions and multiple included files66821+Ref: #assertions-and-multiple-included-files67081+Node: Assertions and multiple -f files67581+Ref: #assertions-and-multiple--f-files67832+Node: Assertions and commodities68229+Ref: #assertions-and-commodities68451+Node: Assertions and prices69631+Ref: #assertions-and-prices69837+Node: Assertions and subaccounts70264+Ref: #assertions-and-subaccounts70485+Node: Assertions and virtual postings70809+Ref: #assertions-and-virtual-postings71047+Node: Assertions and auto postings71179+Ref: #assertions-and-auto-postings71409+Node: Assertions and precision72054+Ref: #assertions-and-precision72236+Node: Posting comments72503+Ref: #posting-comments72649+Node: Tags73026+Ref: #tags73140+Node: Tag values74333+Ref: #tag-values74422+Node: Directives75181+Ref: #directives75308+Node: Directives and multiple files76638+Ref: #directives-and-multiple-files76816+Node: Directive effects77583+Ref: #directive-effects77737+Node: account directive80750+Ref: #account-directive80906+Node: Account comments82304+Ref: #account-comments82454+Node: Account subdirectives82962+Ref: #account-subdirectives83153+Node: Account error checking83295+Ref: #account-error-checking83493+Node: Account display order84682+Ref: #account-display-order84870+Node: Account types85971+Ref: #account-types86112+Node: alias directive89739+Ref: #alias-directive89900+Node: Basic aliases90950+Ref: #basic-aliases91081+Node: Regex aliases91825+Ref: #regex-aliases91982+Node: Combining aliases92872+Ref: #combining-aliases93050+Node: Aliases and multiple files94326+Ref: #aliases-and-multiple-files94530+Node: end aliases directive95109+Ref: #end-aliases-directive95328+Node: Aliases can generate bad account names95477+Ref: #aliases-can-generate-bad-account-names95725+Node: Aliases and account types96310+Ref: #aliases-and-account-types96502+Node: commodity directive97198+Ref: #commodity-directive97372+Node: Commodity directive syntax98557+Ref: #commodity-directive-syntax98742+Node: Commodity error checking100193+Ref: #commodity-error-checking100374+Node: decimal-mark directive100668+Ref: #decimal-mark-directive100850+Node: include directive101247+Ref: #include-directive101411+Node: P directive102323+Ref: #p-directive102468+Node: payee directive103357+Ref: #payee-directive103506+Node: tag directive103979+Ref: #tag-directive104134+Node: Periodic transactions104602+Ref: #periodic-transactions104767+Node: Periodic rule syntax106473+Ref: #periodic-rule-syntax106651+Node: Periodic rules and relative dates107296+Ref: #periodic-rules-and-relative-dates107562+Node: Two spaces between period expression and description!108073+Ref: #two-spaces-between-period-expression-and-description108350+Node: Auto postings109034+Ref: #auto-postings109182+Node: Auto postings and multiple files111619+Ref: #auto-postings-and-multiple-files111783+Node: Auto postings and dates112184+Ref: #auto-postings-and-dates112432+Node: Auto postings and transaction balancing / inferred amounts / balance assertions112607+Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions112963+Node: Auto posting tags113466+Ref: #auto-posting-tags113748+Node: Auto postings on forecast transactions only114384+Ref: #auto-postings-on-forecast-transactions-only114630+Node: Other syntax114877+Ref: #other-syntax114993+Node: Balance assignments115620+Ref: #balance-assignments115776+Node: Balance assignments and prices117149+Ref: #balance-assignments-and-prices117364+Node: Balance assignments and multiple files117575+Ref: #balance-assignments-and-multiple-files117806+Node: Bracketed posting dates117999+Ref: #bracketed-posting-dates118183+Node: D directive118697+Ref: #d-directive118865+Node: apply account directive120465+Ref: #apply-account-directive120645+Node: Y directive121332+Ref: #y-directive121492+Node: Secondary dates122320+Ref: #secondary-dates122474+Node: Star comments123288+Ref: #star-comments123448+Node: Valuation expressions123980+Ref: #valuation-expressions124157+Node: Virtual postings124279+Ref: #virtual-postings124456+Node: Other Ledger directives125893+Ref: #other-ledger-directives126056+Node: CSV126622+Ref: #csv126715+Node: CSV rules cheatsheet128795+Ref: #csv-rules-cheatsheet128924+Node: source130722+Ref: #source130845+Node: separator131725+Ref: #separator131838+Node: skip132378+Ref: #skip132486+Node: date-format133030+Ref: #date-format133151+Node: timezone133875+Ref: #timezone133998+Node: newest-first135003+Ref: #newest-first135141+Node: intra-day-reversed135718+Ref: #intra-day-reversed135872+Node: decimal-mark136320+Ref: #decimal-mark136461+Node: fields list136800+Ref: #fields-list136939+Node: Field assignment138610+Ref: #field-assignment138754+Node: Field names139831+Ref: #field-names139962+Node: date field141165+Ref: #date-field141283+Node: date2 field141331+Ref: #date2-field141472+Node: status field141528+Ref: #status-field141671+Node: code field141720+Ref: #code-field141865+Node: description field141910+Ref: #description-field142070+Node: comment field142129+Ref: #comment-field142284+Node: account field142577+Ref: #account-field142727+Node: amount field143297+Ref: #amount-field143446+Node: currency field146138+Ref: #currency-field146291+Node: balance field146548+Ref: #balance-field146680+Node: if block147052+Ref: #if-block147173+Node: Matchers148581+Ref: #matchers148695+Node: What matchers match149492+Ref: #what-matchers-match149641+Node: Combining matchers150081+Ref: #combining-matchers150249+Node: Match groups150735+Ref: #match-groups150863+Node: if table151610+Ref: #if-table151732+Node: balance-type153294+Ref: #balance-type153423+Node: include154123+Ref: #include154250+Node: Working with CSV154694+Ref: #working-with-csv154841+Node: Rapid feedback155248+Ref: #rapid-feedback155381+Node: Valid CSV155833+Ref: #valid-csv155979+Node: File Extension156711+Ref: #file-extension156884+Node: Reading CSV from standard input157448+Ref: #reading-csv-from-standard-input157672+Node: Reading multiple CSV files157836+Ref: #reading-multiple-csv-files158067+Node: Reading files specified by rule158308+Ref: #reading-files-specified-by-rule158536+Node: Valid transactions159707+Ref: #valid-transactions159906+Node: Deduplicating importing160534+Ref: #deduplicating-importing160729+Node: Setting amounts161765+Ref: #setting-amounts161936+Node: Amount signs164294+Ref: #amount-signs164464+Node: Setting currency/commodity165361+Ref: #setting-currencycommodity165565+Node: Amount decimal places166739+Ref: #amount-decimal-places166945+Node: Referencing other fields167257+Ref: #referencing-other-fields167470+Node: How CSV rules are evaluated168367+Ref: #how-csv-rules-are-evaluated168584+Node: Well factored rules170037+Ref: #well-factored-rules170205+Node: CSV rules examples170529+Ref: #csv-rules-examples170664+Node: Bank of Ireland170729+Ref: #bank-of-ireland170866+Node: Coinbase172328+Ref: #coinbase172466+Node: Amazon173513+Ref: #amazon173638+Node: Paypal175357+Ref: #paypal175465+Node: Timeclock183109+Ref: #timeclock183214+Node: Timedot185392+Ref: #timedot185515+Node: Timedot examples188620+Ref: #timedot-examples188726+Node: PART 3 REPORTING CONCEPTS190897+Ref: #part-3-reporting-concepts191079+Node: Amount formatting parseability191079+Ref: #amount-formatting-parseability191276+Node: Time periods193481+Ref: #time-periods193620+Node: Report start & end date193738+Ref: #report-start-end-date193890+Node: Smart dates195549+Ref: #smart-dates195702+Node: Report intervals197570+Ref: #report-intervals197725+Node: Date adjustment198143+Ref: #date-adjustment198303+Node: Period expressions199154+Ref: #period-expressions199295+Node: Period expressions with a report interval201059+Ref: #period-expressions-with-a-report-interval201293+Node: More complex report intervals201507+Ref: #more-complex-report-intervals201752+Node: Multiple weekday intervals203553+Ref: #multiple-weekday-intervals203742+Node: Depth204564+Ref: #depth204666+Node: Queries204962+Ref: #queries205064+Node: Query types206189+Ref: #query-types206310+Node: Combining query terms209646+Ref: #combining-query-terms209823+Node: Queries and command options211091+Ref: #queries-and-command-options211290+Node: Queries and valuation211539+Ref: #queries-and-valuation211734+Node: Querying with account aliases211963+Ref: #querying-with-account-aliases212174+Node: Querying with cost or value212304+Ref: #querying-with-cost-or-value212481+Node: Pivoting212782+Ref: #pivoting212896+Node: Generating data214673+Ref: #generating-data214805+Node: Forecasting216388+Ref: #forecasting216513+Node: --forecast217044+Ref: #forecast217175+Node: Inspecting forecast transactions218221+Ref: #inspecting-forecast-transactions218423+Node: Forecast reports219553+Ref: #forecast-reports219726+Node: Forecast tags220662+Ref: #forecast-tags220822+Node: Forecast period in detail221282+Ref: #forecast-period-in-detail221476+Node: Forecast troubleshooting222370+Ref: #forecast-troubleshooting222538+Node: Budgeting223441+Ref: #budgeting223561+Node: Cost reporting223998+Ref: #cost-reporting224132+Node: Recording costs224793+Ref: #recording-costs224929+Node: Reporting at cost226520+Ref: #reporting-at-cost226695+Node: Equity conversion postings227285+Ref: #equity-conversion-postings227499+Node: Inferring equity conversion postings229930+Ref: #inferring-equity-conversion-postings230193+Node: Combining costs and equity conversion postings230945+Ref: #combining-costs-and-equity-conversion-postings231255+Node: Requirements for detecting equity conversion postings232243+Ref: #requirements-for-detecting-equity-conversion-postings232565+Node: Infer cost and equity by default ?233765+Ref: #infer-cost-and-equity-by-default233994+Node: Value reporting234202+Ref: #value-reporting234344+Node: -V Value235118+Ref: #v-value235250+Node: -X Value in specified commodity235445+Ref: #x-value-in-specified-commodity235646+Node: Valuation date235795+Ref: #valuation-date235972+Node: Finding market price236755+Ref: #finding-market-price236966+Node: --infer-market-prices market prices from transactions238135+Ref: #infer-market-prices-market-prices-from-transactions238417+Node: Valuation commodity241179+Ref: #valuation-commodity241398+Node: Simple valuation examples242611+Ref: #simple-valuation-examples242815+Node: --value Flexible valuation243474+Ref: #value-flexible-valuation243684+Node: More valuation examples245328+Ref: #more-valuation-examples245543+Node: Interaction of valuation and queries246813+Ref: #interaction-of-valuation-and-queries247060+Node: Effect of valuation on reports247532+Ref: #effect-of-valuation-on-reports247735+Node: PART 4 COMMANDS255432+Ref: #part-4-commands255581+Node: Commands overview255960+Ref: #commands-overview256094+Node: DATA ENTRY256273+Ref: #data-entry256397+Node: DATA CREATION256596+Ref: #data-creation256750+Node: DATA MANAGEMENT256868+Ref: #data-management257033+Node: REPORTS FINANCIAL257154+Ref: #reports-financial257329+Node: REPORTS VERSATILE257634+Ref: #reports-versatile257807+Node: REPORTS BASIC258060+Ref: #reports-basic258212+Node: HELP258721+Ref: #help258843+Node: ADD-ONS258953+Ref: #add-ons259059+Node: accounts259638+Ref: #accounts259771+Node: activity261658+Ref: #activity261777+Node: add262151+Ref: #add262261+Node: aregister265072+Ref: #aregister265193+Node: aregister and posting dates268081+Ref: #aregister-and-posting-dates268226+Node: balance268982+Ref: #balance269108+Node: balance features270093+Ref: #balance-features270233+Node: Simple balance report272199+Ref: #simple-balance-report272384+Node: Balance report line format274009+Ref: #balance-report-line-format274211+Node: Filtered balance report276369+Ref: #filtered-balance-report276561+Node: List or tree mode276888+Ref: #list-or-tree-mode277056+Node: Depth limiting278401+Ref: #depth-limiting278567+Node: Dropping top-level accounts279168+Ref: #dropping-top-level-accounts279368+Node: Showing declared accounts279678+Ref: #showing-declared-accounts279877+Node: Sorting by amount280408+Ref: #sorting-by-amount280575+Node: Percentages281245+Ref: #percentages281404+Node: Multi-period balance report281952+Ref: #multi-period-balance-report282152+Node: Balance change end balance284427+Ref: #balance-change-end-balance284636+Node: Balance report types286064+Ref: #balance-report-types286245+Node: Calculation type286743+Ref: #calculation-type286898+Node: Accumulation type287447+Ref: #accumulation-type287627+Node: Valuation type288529+Ref: #valuation-type288717+Node: Combining balance report types289718+Ref: #combining-balance-report-types289912+Node: Budget report291750+Ref: #budget-report291912+Node: Budget report start date297566+Ref: #budget-report-start-date297744+Node: Budgets and subaccounts299076+Ref: #budgets-and-subaccounts299283+Node: Selecting budget goals302723+Ref: #selecting-budget-goals302922+Node: Budget vs forecast303957+Ref: #budget-vs-forecast304116+Node: Balance report layout305746+Ref: #balance-report-layout305926+Node: Useful balance reports314111+Ref: #useful-balance-reports314271+Node: balancesheet315356+Ref: #balancesheet315501+Node: balancesheetequity316828+Ref: #balancesheetequity316986+Node: cashflow318382+Ref: #cashflow318513+Node: check319948+Ref: #check320062+Node: Default checks320866+Ref: #default-checks320992+Node: Strict checks321489+Ref: #strict-checks321634+Node: Other checks322114+Ref: #other-checks322256+Node: Custom checks322789+Ref: #custom-checks322946+Node: More about specific checks323363+Ref: #more-about-specific-checks323525+Node: close324231+Ref: #close324342+Node: close and balance assertions327807+Ref: #close-and-balance-assertions327985+Node: Example retain earnings329136+Ref: #example-retain-earnings329353+Node: Example migrate balances to a new file329785+Ref: #example-migrate-balances-to-a-new-file330050+Node: Example excluding closing/opening transactions330626+Ref: #example-excluding-closingopening-transactions330875+Node: codes332093+Ref: #codes332210+Node: commodities333074+Ref: #commodities333202+Node: demo333272+Ref: #demo333393+Node: descriptions334309+Ref: #descriptions334439+Node: diff334730+Ref: #diff334845+Node: files335887+Ref: #files335996+Node: help336137+Ref: #help-1336246+Node: import337619+Ref: #import337742+Node: Deduplication338850+Ref: #deduplication338975+Node: Import testing340994+Ref: #import-testing341159+Node: Importing balance assignments342002+Ref: #importing-balance-assignments342208+Node: Commodity display styles342857+Ref: #commodity-display-styles343030+Node: incomestatement343159+Ref: #incomestatement343301+Node: notes344629+Ref: #notes344751+Node: payees345113+Ref: #payees345228+Node: prices345747+Ref: #prices345862+Node: print346515+Ref: #print346630+Node: print explicitness347606+Ref: #print-explicitness347749+Node: print amount style348528+Ref: #print-amount-style348698+Node: print parseability349750+Ref: #print-parseability349922+Node: print other features350671+Ref: #print-other-features350850+Node: print output format351371+Ref: #print-output-format351519+Node: register354638+Ref: #register354760+Node: Custom register output359791+Ref: #custom-register-output359922+Node: rewrite361266+Ref: #rewrite361384+Node: Re-write rules in a file363282+Ref: #re-write-rules-in-a-file363445+Node: Diff output format364594+Ref: #diff-output-format364777+Node: rewrite vs print --auto365869+Ref: #rewrite-vs.-print---auto366029+Node: roi366585+Ref: #roi366692+Node: Spaces and special characters in --inv and --pnl368504+Ref: #spaces-and-special-characters-in---inv-and---pnl368744+Node: Semantics of --inv and --pnl369232+Ref: #semantics-of---inv-and---pnl369471+Node: IRR and TWR explained371321+Ref: #irr-and-twr-explained371481+Node: stats374734+Ref: #stats374842+Node: tags376229+Ref: #tags-1376336+Node: test377345+Ref: #test377438+Node: PART 5 COMMON TASKS378180+Ref: #part-5-common-tasks378326+Node: Getting help378624+Ref: #getting-help378765+Node: Constructing command lines379525+Ref: #constructing-command-lines379726+Node: Starting a journal file380383+Ref: #starting-a-journal-file380585+Node: Setting LEDGER_FILE381787+Ref: #setting-ledger_file381979+Node: Setting opening balances382936+Ref: #setting-opening-balances383137+Node: Recording transactions386278+Ref: #recording-transactions386467+Node: Reconciling387023+Ref: #reconciling387175+Node: Reporting389432+Ref: #reporting389581+Node: Migrating to a new file393566+Ref: #migrating-to-a-new-file393723+Node: BUGS394022+Ref: #bugs394112+Node: Troubleshooting394991+Ref: #troubleshooting395091  End Tag Table