diff --git a/CHANGES.md b/CHANGES.md --- a/CHANGES.md +++ b/CHANGES.md @@ -26,6 +26,48 @@ User-visible changes in the hledger command line tool and library. +# 1.50.3 2025-11-18 + +Fixes + +- hledger versions 1.50-1.50.2 ran much slower than normal (depending on the speed of your hard drive). + This 1.50.3 release fixes that; so please upgrade, and avoid those older 1.50 releases. + [#2493] + +- A regression in 1.50, where very large dates could produce wrong reports, has been fixed. + (Affecting dates outside the range -25252734927764696-04-22..25252734927768413-06-12 + on 64 bit machines, or -5877752-05-08..5881469-05-27 on 32 bit machines.) + [#2479] + +- If the `LEDGER_FILE` environment variable is set to a nonexistent file, we now report an error + rather than silently falling back on a default file path, which was confusing. + Also, we no longer support the legacy `LEDGER` environment variable as a fallback. + [#2485] + +- `setup` now shows tidier output when a LEDGER_FILE or default file is not found, + +- `add` now checks balance assertions more robustly, with awareness of how everything is ordered in the journal. + Also, it now allows adding balance assignments. + [#2478] + +- `check accounts` no longer garbles non-ascii account names in its output. + [#2469] + +- We now escape special characters properly when passing arguments to addons + (with just one level of quoting/escaping, not two). + And related docs have been improved. + (Caleb Maclennan, Simon Michael, [#2468]) + +- Internal report code which could produce certain date-related errors has been made robust again. + (Stephen Morgan) + +- The old "threaded" build flag, which cabal could turn off, has been dropped. + This will hopefully prevent wrong builds like Debian's #1120833. + [#2495] + +- Docs updated: add, areg, argument files, check, close, csv, depth, print, print, Special characters, Value reporting + + # 1.50.2 2025-09-26 Fixes @@ -35,10 +77,10 @@ [#2465] - The doc for `--depth` has been clarified, and now mentions the use of quotes. - (Quả Cầu, Simon Michael, [hledger_site#140]) + (Lý Minh Nhật, Simon Michael, [hledger_site#140]) - A typo was fixed in the --depth example in `register`'s doc. - ([hledger_site#140], reported by Quả Cầu) + ([hledger_site#140], reported by Lý Minh Nhật) - Our package bounds now avoid hashtables 1.3.x, which fails to build with some gcc versions (see https://github.com/gregorycollins/hashtables/issues/97)). diff --git a/Hledger/Cli.hs b/Hledger/Cli.hs --- a/Hledger/Cli.hs +++ b/Hledger/Cli.hs @@ -107,7 +107,7 @@ import Data.Function ((&)) import Data.Functor ((<&>)) import Data.List -import qualified Data.List.NonEmpty as NE +import Data.List.NonEmpty qualified as NE import Data.Maybe (isJust, fromMaybe, fromJust) import Data.Text (pack, Text) import Data.Time.Clock.POSIX (getPOSIXTime) @@ -452,9 +452,9 @@ let addonargs0 = filter (/="--") $ supportedgenargsfromconf <> confcmdargs <> cliargswithoutcmd addonargs = dropCliSpecificOpts addonargs0 - shellcmd = printf "%s-%s %s" progname cmdname (unwords' addonargs) :: String + shellcmd = printf "%s-%s %s" progname cmdname (unwords $ map quoteForCommandLine addonargs) :: String dbgio "addon command selected" cmdname - dbgio "addon command arguments after removing cli-specific opts" (map quoteIfNeeded addonargs) + dbgio "addon command arguments" addonargs dbg1IO "running addon" shellcmd system shellcmd >>= exitWith diff --git a/Hledger/Cli/Anchor.hs b/Hledger/Cli/Anchor.hs --- a/Hledger/Cli/Anchor.hs +++ b/Hledger/Cli/Anchor.hs @@ -7,15 +7,15 @@ headerDateSpanCell, ) where -import qualified Data.Text as Text +import Data.Text qualified as Text import Data.Text (Text) import Data.Time (Day) import Data.Maybe (fromMaybe) -import qualified Text.URI as Uri -import qualified Text.URI.QQ as UriQQ +import Text.URI qualified as Uri +import Text.URI.QQ qualified as UriQQ -import qualified Hledger.Write.Spreadsheet as Spr +import Hledger.Write.Spreadsheet qualified as Spr import Hledger.Write.Spreadsheet (headerCell) import Hledger.Utils.IO (error') import Hledger.Utils.Text (quoteIfSpaced) diff --git a/Hledger/Cli/Anon.hs b/Hledger/Cli/Anon.hs --- a/Hledger/Cli/Anon.hs +++ b/Hledger/Cli/Anon.hs @@ -18,7 +18,7 @@ import Data.Hashable (hash) import Data.Word (Word32) import Numeric (showHex) -import qualified Data.Text as T +import Data.Text qualified as T import Hledger.Data import Data.Map (mapKeys) diff --git a/Hledger/Cli/CliOptions.hs b/Hledger/Cli/CliOptions.hs --- a/Hledger/Cli/CliOptions.hs +++ b/Hledger/Cli/CliOptions.hs @@ -90,17 +90,17 @@ ) where -import qualified Control.Exception as C +import Control.Exception qualified as C import Control.Monad (when) import Data.Char import Data.Default import Data.List.Extra (intercalate, isInfixOf, nubSort) -import qualified Data.List.NonEmpty as NE (NonEmpty, fromList, nonEmpty) +import Data.List.NonEmpty qualified as NE (NonEmpty, fromList, nonEmpty) import Data.List.Split (splitOn) import Data.Maybe --import Data.String.Here -- import Data.Text (Text) -import qualified Data.Text as T +import Data.Text qualified as T import Data.Void (Void) import GitHash (tGitInfoCwdTry) import Safe diff --git a/Hledger/Cli/Commands.hs b/Hledger/Cli/Commands.hs --- a/Hledger/Cli/Commands.hs +++ b/Hledger/Cli/Commands.hs @@ -60,7 +60,7 @@ import Data.List import Data.List.Extra (groupSortOn, nubSort) import Data.Text (Text) -import qualified Data.Text as T +import Data.Text qualified as T import Data.Time.Calendar import Safe (headErr) import String.ANSI diff --git a/Hledger/Cli/Commands/Accounts.hs b/Hledger/Cli/Commands/Accounts.hs --- a/Hledger/Cli/Commands/Accounts.hs +++ b/Hledger/Cli/Commands/Accounts.hs @@ -23,8 +23,8 @@ import Control.Monad (forM_) import Data.List import Data.Maybe (fromMaybe) -import qualified Data.Text as T -import qualified Data.Text.IO as T +import Data.Text qualified as T +import Data.Text.IO qualified as T import Safe (headDef) import System.Console.CmdArgs.Explicit as C diff --git a/Hledger/Cli/Commands/Activity.hs b/Hledger/Cli/Commands/Activity.hs --- a/Hledger/Cli/Commands/Activity.hs +++ b/Hledger/Cli/Commands/Activity.hs @@ -39,8 +39,8 @@ _ -> rspec spanps = case mspans of Nothing -> [] - Just x -> map (\spn -> (spn, filter (postingInRange spn) ps)) . snd $ periodDataToList x - postingInRange (b, e) p = postingDate p >= b && postingDate p < e + Just x -> map (\spn -> (spn, filter (postingInRange spn) ps)) $ dayPartitionToList x + postingInRange (b, e) p = postingDate p >= b && postingDate p <= e -- same as Register -- should count transactions, not postings ? -- ps = sortBy (comparing postingDate) $ filterempties $ filter matchapats $ filterdepth $ journalPostings j diff --git a/Hledger/Cli/Commands/Add.hs b/Hledger/Cli/Commands/Add.hs --- a/Hledger/Cli/Commands/Add.hs +++ b/Hledger/Cli/Commands/Add.hs @@ -1,10 +1,16 @@ {-| -A history-aware add command to help with data entry. -|-} +A history-aware, tab-completing interactive add command to help with data entry. +-} {-# OPTIONS_GHC -fno-warn-missing-signatures -fno-warn-unused-do-bind #-} -{-# LANGUAGE ScopedTypeVariables, RecordWildCards, TypeOperators, FlexibleContexts, OverloadedStrings, PackageImports, LambdaCase #-} +{-# LANGUAGE FlexibleContexts #-} +{-# LANGUAGE LambdaCase #-} +{-# LANGUAGE OverloadedStrings #-} +{-# LANGUAGE PackageImports #-} +{-# LANGUAGE RecordWildCards #-} +{-# LANGUAGE ScopedTypeVariables #-} {-# LANGUAGE TemplateHaskell #-} +{-# LANGUAGE TypeOperators #-} module Hledger.Cli.Commands.Add ( addmode @@ -25,14 +31,14 @@ import Data.List (isPrefixOf, nub) import Data.Maybe (fromJust, fromMaybe, isJust) import Data.Text (Text) -import qualified Data.Text as T -import qualified Data.Text.IO as T -import qualified Data.Text.Lazy as TL -import qualified Data.Text.Lazy.IO as TL +import Data.Text qualified as T +import Data.Text.IO qualified as T +import Data.Text.Lazy qualified as TL +import Data.Text.Lazy.IO qualified as TL import Data.Time.Calendar (Day, toGregorian) import Data.Time.Format (formatTime, defaultTimeLocale) import Lens.Micro ((^.)) -import Safe (headDef, headMay, atMay) +import Safe (headDef, headMay, atMay, lastMay) import System.Console.CmdArgs.Explicit (flagNone) import System.Console.Haskeline (runInputT, defaultSettings, setComplete) import System.Console.Haskeline.Completion (CompletionFunc, completeWord, isFinished, noCompletion, simpleCompletion) @@ -203,11 +209,12 @@ ,tcomment=txnCmnt ,tpostings=esPostings } - case balanceTransaction defbalancingopts t of -- imprecise balancing (?) + bopts = balancingopts_ (inputopts_ esOpts) + case balanceTransactionInJournal t esJournal bopts of Right t' -> confirmedTransactionWizard prevInput es (EndStage t' : stack) Left err -> do - liftIO (hPutStrLn stderr $ "\n" ++ (capitalize err) ++ "please re-enter.") + liftIO (hPutStrLn stderr $ "\n" ++ (capitalize err) ++ ", please re-enter.") let notFirstEnterPost stage = case stage of EnterNewPosting _ Nothing -> False _ -> True @@ -231,9 +238,10 @@ confirmedTransactionWizard prevInput es{esPostings=init esPostings} (dropWhile notPrevAmountAndNotEnterDesc stack) EnterAmountAndComment txnParams account -> amountAndCommentWizard prevInput es >>= \case - Just (amt, assertion, (comment, tags, pdate1, pdate2)) -> do - let p = nullposting{paccount=T.pack $ stripbrackets account - ,pamount=mixedAmount amt + Just (mamt, assertion, (comment, tags, pdate1, pdate2)) -> do + let mixedamt = maybe missingmixedamt mixedAmount mamt + p = nullposting{paccount=T.pack $ stripbrackets account + ,pamount=mixedamt ,pcomment=T.dropAround isNewline comment ,ptype=accountNamePostingType $ T.pack account ,pbalanceassertion = assertion @@ -241,7 +249,7 @@ ,pdate2=pdate2 ,ptags=tags } - amountAndCommentString = showAmount amt ++ T.unpack (if T.null comment then "" else " ;" <> comment) + amountAndCommentString = showMixedAmountOneLine mixedamt ++ T.unpack (if T.null comment then "" else " ;" <> comment) prevAmountAndCmnt' = replaceNthOrAppend (length esPostings) amountAndCommentString (prevAmountAndCmnt prevInput) es' = es{esPostings=esPostings++[p], esArgs=drop 1 esArgs} -- Include a dummy posting to balance the unfinished transation in assertion checking @@ -249,8 +257,17 @@ ,tdate = txnDate txnParams ,tdescription = txnDesc txnParams } bopts = balancingopts_ (inputopts_ esOpts) - validated = balanceTransaction bopts dummytxn >>= transactionCheckAssertions bopts esJournal - case validated of + balanceassignment = mixedamt==missingmixedamt && isJust assertion + etxn + -- If the new posting is doing a balance assignment, + -- don't attempt to balance the transaction or check assertions yet + | balanceassignment = Right dummytxn + -- Otherwise, balance the transaction in context of the whole journal, + -- maybe filling its balance assignments if any, + -- and maybe checking all the journal's balance assertions. + | otherwise = balanceTransactionInJournal dummytxn esJournal bopts + + case etxn of Left err -> do liftIO (hPutStrLn stderr err) confirmedTransactionWizard prevInput es (EnterAmountAndComment txnParams account : stack) @@ -272,6 +289,23 @@ where replaceNthOrAppend n newElem xs = take n xs ++ [newElem] ++ drop (n + 1) xs + +-- | Balance and check a transaction with awareness of the whole journal it will be added to. +-- This means add it to the journal, balance it, calculate any balance assignments in it, +-- then maybe check all the journal's balance assertions, +-- then return the now fully balanced and checked transaction, or an error message. +balanceTransactionInJournal :: Transaction -> Journal -> BalancingOpts -> Either String Transaction +balanceTransactionInJournal t j bopts = do + -- Add the transaction at the end of the journal, as the add command will. + let j' = j{jtxns = jtxns j ++ [t]} + -- Try to balance and check the whole journal, and specifically the new transaction. + Journal{jtxns=ts} <- journalBalanceTransactions bopts j' + -- Extract the balanced & checked transaction. + maybe + (Left "confirmedTransactionWizard: unexpected empty journal") -- should not happen + Right + (lastMay ts) + -- | A workaround we seem to need for #2410 right now: wizards' input-reading functions disrupt ANSI codes -- somehow, so these variants first print the ANSI coded prompt as ordinary output, then do the input with no prompt. line' prompt = output prompt >> line "" @@ -346,7 +380,7 @@ type Comment = (Text, [Tag], Maybe Day, Maybe Day) -amountAndCommentWizard :: PrevInput -> EntryState -> Wizard Haskeline (Maybe (Amount, Maybe BalanceAssertion, Comment)) +amountAndCommentWizard :: PrevInput -> EntryState -> Wizard Haskeline (Maybe (Maybe Amount, Maybe BalanceAssertion, Comment)) amountAndCommentWizard previnput@PrevInput{..} entrystate@EntryState{..} = do let pnum = length esPostings + 1 (mhistoricalp,followedhistoricalsofar) = @@ -383,16 +417,16 @@ "" (T.pack s) nodefcommodityj = esJournal{jparsedefaultcommodity=Nothing} - amountandcommentp :: JournalParser Identity (Amount, Maybe BalanceAssertion, Comment) + amountandcommentp :: JournalParser Identity (Maybe Amount, Maybe BalanceAssertion, Comment) amountandcommentp = do - a <- amountp + mamt <- optional amountp lift skipNonNewlineSpaces - assertion <- optional balanceassertionp + massertion <- optional balanceassertionp com <- T.pack <$> fromMaybe "" `fmap` optional (char ';' >> many anySingle) case rtp (postingcommentp (let (y,_,_) = toGregorian esDefDate in Just y)) (T.cons ';' com) of Left err -> fail $ customErrorBundlePretty err -- Keep our original comment string from the user to add to the journal - Right (_, tags, date1', date2') -> return $ (a, assertion, (com, tags, date1', date2')) + Right (_, tags, date1', date2') -> return $ (mamt, massertion, (com, tags, date1', date2')) balancingamt = maNegate . sumPostings $ filter isReal esPostings balancingamtfirstcommodity = mixed . take 1 $ amounts balancingamt showamt = wbUnpack . showMixedAmountB defaultFmt . mixedAmountSetPrecision diff --git a/Hledger/Cli/Commands/Add.txt b/Hledger/Cli/Commands/Add.txt --- a/Hledger/Cli/Commands/Add.txt +++ b/Hledger/Cli/Commands/Add.txt @@ -62,24 +62,22 @@ add and balance assertions -Since hledger 1.43, whenever you enter a posting amount, add will -re-check all balance assertions in the journal, and if any of them fail, -it will report the problem and ask for the amount again. - -You can also add a new balance assertion, following the amount as in -journal format. - -The new transaction's date, and the new posting's posting date if any -(entered in a comment following the amount), will influence assertion -checking. +Since hledger 1.43, you can add a balance assertion by writing +AMOUNT = BALANCE when asked for an amount. Eg 100 = 500. -You can use -I/--ignore-assertions to disable assertion checking -temporarily. +Also, each time you enter a new amount, hledger re-checks all balance +assertions in the journal and rejects the new amount if it would make +any of them fail. You can run add with -I/--ignore-assertions to disable +balance assertion checking. add and balance assignments -Balance assignments are not recalculated during a hledger add session. -When add runs, it sees the journal with all balance assignments already -processed and converted to assertions. So if you add a new posting which -is dated earlier than a balance assignment, it will break the assertion -and be rejected. You can make it work by using hledger add -I. +Since hledger 1.50.3, you can add a balance assignment by writing += BALANCE (or ==, =* etc) when asked for an amount. The missing amount +will be calculated automatically. + +add normally won't let you add a new posting which is dated earlier than +an existing balance assignment. (Because when add runs, existing balance +assignments have already been calculated and converted to amounts and +balance assertions.) You can allow it by disabling balance assertion +checking with -I. diff --git a/Hledger/Cli/Commands/Aregister.hs b/Hledger/Cli/Commands/Aregister.hs --- a/Hledger/Cli/Commands/Aregister.hs +++ b/Hledger/Cli/Commands/Aregister.hs @@ -24,14 +24,14 @@ import Data.Maybe (fromMaybe) import Data.Text (Text) import Data.Foldable (for_) -import qualified Data.Map as Map -import qualified Data.Text as T -import qualified Data.Text.Lazy as TL -import qualified Data.Text.Lazy.Builder as TB +import Data.Map qualified as Map +import Data.Text qualified as T +import Data.Text.Lazy qualified as TL +import Data.Text.Lazy.Builder qualified as TB import Control.Monad (when) -import qualified Lucid as L hiding (Html) +import Lucid qualified as L hiding (Html) import System.Console.CmdArgs.Explicit (flagNone, flagReq) -import qualified System.IO as IO +import System.IO qualified as IO import Text.Tabular.AsciiWide hiding (render) import Hledger @@ -40,7 +40,7 @@ import Hledger.Write.Csv (CSV, printCSV, printTSV) import Hledger.Write.Html (formatRow, htmlAsLazyText, toHtml) import Hledger.Write.Ods (printFods) -import qualified Hledger.Write.Spreadsheet as Spr +import Hledger.Write.Spreadsheet qualified as Spr aregistermode = hledgerCommandMode $(embedFileRelative "Hledger/Cli/Commands/Aregister.txt") diff --git a/Hledger/Cli/Commands/Aregister.txt b/Hledger/Cli/Commands/Aregister.txt --- a/Hledger/Cli/Commands/Aregister.txt +++ b/Hledger/Cli/Commands/Aregister.txt @@ -33,9 +33,10 @@ 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. +necessarily in historical mode). As a quick rule of thumb: + +- aregister is best when reconciling real-world asset/liability accounts +- register is best when reviewing individual 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 diff --git a/Hledger/Cli/Commands/Balance.hs b/Hledger/Cli/Commands/Balance.hs --- a/Hledger/Cli/Commands/Balance.hs +++ b/Hledger/Cli/Commands/Balance.hs @@ -281,14 +281,14 @@ #if !MIN_VERSION_base(4,20,0) import Data.List (foldl') #endif -import qualified Data.Map as Map -import qualified Data.Set as S +import Data.Map qualified as Map +import Data.Set qualified as S import Data.Maybe (mapMaybe, fromMaybe) import Data.Tuple (swap) import Data.Text (Text) -import qualified Data.Text as T -import qualified Data.Text.Lazy as TL -import qualified Data.Text.Lazy.Builder as TB +import Data.Text qualified as T +import Data.Text.Lazy qualified as TL +import Data.Text.Lazy.Builder qualified as TB import Data.Time (addDays, fromGregorian) import System.Console.CmdArgs.Explicit as C (flagNone, flagReq, flagOpt) import Safe (headMay, maximumMay) @@ -296,7 +296,7 @@ (Header(..), Align(..), Properties(..), Cell(..), Table(..), TableOpts(..), cellWidth, concatTables, renderColumns, renderRowB, renderTableByRowsB, textCell) -import qualified System.IO as IO +import System.IO qualified as IO import Hledger import Hledger.Cli.CliOptions @@ -308,7 +308,7 @@ import Hledger.Write.Spreadsheet (rawTableContent, headerCell, addHeaderBorders, addRowSpanHeader, cellFromMixedAmount, cellsFromMixedAmount) -import qualified Hledger.Write.Spreadsheet as Ods +import Hledger.Write.Spreadsheet qualified as Ods -- | Command line options for this command. diff --git a/Hledger/Cli/Commands/Check.txt b/Hledger/Cli/Commands/Check.txt --- a/Hledger/Cli/Commands/Check.txt +++ b/Hledger/Cli/Commands/Check.txt @@ -18,9 +18,9 @@ If you are an Emacs user, you can also configure flycheck-hledger to run these checks, providing instant feedback as you edit the journal. -Here are the checks currently available. Generally, they are performed -in the order they are shown here (and only the first failure is -reported). +Here are the checks currently available. They are generally checked in +the order they are shown here, and only the first failure will be +reported. Basic checks @@ -33,30 +33,30 @@ - autobalanced - all transactions are balanced, after automatically inferring missing amounts and conversion rates and then converting - amounts to cost. This ensures that each transaction's entry is well - formed. + amounts to cost. This ensures that each transaction's journal entry is + well formed. - assertions - all balance assertions in the journal are passing. - Balance assertions are a strong defense against errors; they help - catch many problems. If this check gets in your way, you can disable - it with -I/--ignore-assertions. Or you can add that to your config - file to disable it by default (and then use -s/--strict or - hledger check assertions to enable it). + Balance assertions are a strong defense against errors, catching many + problems. This check is on by default, but if it gets in your way, you + can disable it temporarily with -I/--ignore-assertions, or as a + default by adding that flag to your config file. (Then use -s/--strict + or hledger check assertions when you want to enable it). Strict checks -These additional checks are performed by all commands when the --s/--strict flag is used (strict mode). They provide extra -error-catching power to keep your data clean and correct. Strict mode -also always enables the assertions check. +When the -s/--strict flag is used (AKA strict mode), all commands will +perform the following additional checks (and assertions, above). These +provide extra error-catching power to help you keep your data clean and +correct: -- balanced - like autobalanced, but all conversions between commodities - must use explicit cost notation or equity postings. This prevents - wrong conversions caused by typos. +- balanced - like autobalanced, but implicit conversions between + commodities are not allowed; all conversion transactions must use cost + notation or equity postings. This prevents wrong conversions caused by + typos. - commodities - all commodity symbols used must be declared. This guards - against mistyping or omitting commodity symbols. Declaring commodities - also sets their precision for display and transaction balancing. + against mistyping or omitting commodity symbols. - accounts - all account names used must be declared. This prevents the use of mis-spelled or outdated account names. @@ -84,10 +84,9 @@ encourage adding balance assertions for your active asset/liability accounts, which in turn should encourage you to reconcile regularly with those real world balances - another strong defense against - errors. hledger close --assert can help generate assertion entries. - Over time the older assertions become somewhat redundant, and you can - remove them if you like (they don't affect performance much, but they - add some noise to the journal). + errors. (hledger close --assert >>$LEDGER_FILE is a convenient way to + add new balance assertions. Later these become quite redundant, and + you might choose to remove them to reduce clutter.) - uniqueleafnames - no two accounts may have the same last account name part (eg the checking in assets:bank:checking). This ensures each @@ -99,8 +98,8 @@ You can build your own custom checks with add-on command scripts. See also Cookbook > Scripting. Here are some examples from hledger/bin/: -- hledger-check-tagfiles - all tag values containing / (a forward slash) - exist as file paths +- hledger-check-tagfiles - all tag values containing / exist as file + paths - hledger-check-fancyassertions - more complex balance assertions are passing diff --git a/Hledger/Cli/Commands/Close.hs b/Hledger/Cli/Commands/Close.hs --- a/Hledger/Cli/Commands/Close.hs +++ b/Hledger/Cli/Commands/Close.hs @@ -11,8 +11,8 @@ import Data.Function (on) import Data.List (groupBy) import Data.Maybe (fromMaybe) -import qualified Data.Text as T -import qualified Data.Text.IO as T +import Data.Text qualified as T +import Data.Text.IO qualified as T import Data.Time.Calendar (addDays) import System.Console.CmdArgs.Explicit as C diff --git a/Hledger/Cli/Commands/Close.txt b/Hledger/Cli/Commands/Close.txt --- a/Hledger/Cli/Commands/Close.txt +++ b/Hledger/Cli/Commands/Close.txt @@ -36,10 +36,18 @@ all - also round cost amounts to precision (can unbalance transactions) -close has six modes, selected by choosing one of the mode flags (--close -is the default). They all do much the same operation, but with different -defaults, useful in different situations. +close has six modes, selected by choosing one of the mode flags: +--clopen, --close (default), --open, --assert, --assign, or --retain. +They are all doing the same kind of operation, but with different +defaults for different situations. +The journal entries generated by close will have a clopen: tag, which is +helpful when you want to exclude them from reports. If the main journal +file name contains a number, the tag's value will be that base file name +with the number incremented. Eg if the journal file is 2025.journal, the +tag will be clopen:2026. Or you can set the tag value by providing an +argument to the mode flag. Eg --close=foo or --clopen=2025-main. + close --clopen This is useful if migrating balances to a new journal file at the start @@ -77,11 +85,6 @@ Assertions will be added indicating and checking the new balances of the closed/opened accounts. -The generated transactions will have a clopen: tag. If the main -journal's base file name contains a number (eg a year number), the tag's -value will be that base file name with the number incremented. Or you -can choose the tag value yourself, by using --clopen=TAGVAL. - close --close This prints just the closing balances transaction of --clopen. It is the @@ -137,11 +140,12 @@ In all modes, the following things can be overridden: - the accounts to be closed/opened, with account query arguments +- the closing/opening dates, with -e OPENDATE - the balancing account, with --close-acct=ACCT and/or --open-acct=ACCT - the transaction descriptions, with --close-desc=DESC and --open-desc=DESC -- the transaction's tag value, with a --MODE=NEW option argument -- the closing/opening dates, with -e OPENDATE +- the transactions' clopen tag value, with a TAGVAL argument for the + mode flag (see above). By default, the closing date is yesterday, or the journal's end date, whichever is later; and the opening date is always one day after the diff --git a/Hledger/Cli/Commands/Codes.hs b/Hledger/Cli/Commands/Codes.hs --- a/Hledger/Cli/Commands/Codes.hs +++ b/Hledger/Cli/Commands/Codes.hs @@ -15,8 +15,8 @@ ,codes ) where -import qualified Data.Text as T -import qualified Data.Text.IO as T +import Data.Text qualified as T +import Data.Text.IO qualified as T import Hledger import Hledger.Cli.CliOptions diff --git a/Hledger/Cli/Commands/Commodities.hs b/Hledger/Cli/Commands/Commodities.hs --- a/Hledger/Cli/Commands/Commodities.hs +++ b/Hledger/Cli/Commands/Commodities.hs @@ -12,9 +12,9 @@ ,commodities ) where -import qualified Data.Map as M -import qualified Data.Set as S -import qualified Data.Text.IO as T +import Data.Map qualified as M +import Data.Set qualified as S +import Data.Text.IO qualified as T import System.Console.CmdArgs.Explicit import Hledger diff --git a/Hledger/Cli/Commands/Demo.hs b/Hledger/Cli/Commands/Demo.hs --- a/Hledger/Cli/Commands/Demo.hs +++ b/Hledger/Cli/Commands/Demo.hs @@ -47,7 +47,7 @@ import Control.Applicative ((<|>)) import Data.ByteString as B (ByteString) import Data.Maybe -import qualified Data.ByteString.Char8 as B +import Data.ByteString.Char8 qualified as B import Safe (tailMay) import System.IO.Temp (withSystemTempFile) import System.IO (hClose) diff --git a/Hledger/Cli/Commands/Descriptions.hs b/Hledger/Cli/Commands/Descriptions.hs --- a/Hledger/Cli/Commands/Descriptions.hs +++ b/Hledger/Cli/Commands/Descriptions.hs @@ -15,7 +15,7 @@ ) where import Data.List.Extra (nubSort) -import qualified Data.Text.IO as T +import Data.Text.IO qualified as T import Hledger import Hledger.Cli.CliOptions diff --git a/Hledger/Cli/Commands/Diff.hs b/Hledger/Cli/Commands/Diff.hs --- a/Hledger/Cli/Commands/Diff.hs +++ b/Hledger/Cli/Commands/Diff.hs @@ -18,7 +18,7 @@ import Data.Maybe (fromJust) import Data.Time (diffDays) import Data.Either (partitionEithers) -import qualified Data.Text.IO as T +import Data.Text.IO qualified as T import Lens.Micro (set) import Safe (headDef) diff --git a/Hledger/Cli/Commands/Files.hs b/Hledger/Cli/Commands/Files.hs --- a/Hledger/Cli/Commands/Files.hs +++ b/Hledger/Cli/Commands/Files.hs @@ -11,7 +11,7 @@ ,files ) where -import qualified Data.Text as T +import Data.Text qualified as T import Safe (headMay) import Hledger diff --git a/Hledger/Cli/Commands/Import.hs b/Hledger/Cli/Commands/Import.hs --- a/Hledger/Cli/Commands/Import.hs +++ b/Hledger/Cli/Commands/Import.hs @@ -11,7 +11,7 @@ import Control.Monad import Data.List -import qualified Data.Text.IO as T +import Data.Text.IO qualified as T import System.Console.CmdArgs.Explicit import Text.Printf diff --git a/Hledger/Cli/Commands/Incomestatement.hs b/Hledger/Cli/Commands/Incomestatement.hs --- a/Hledger/Cli/Commands/Incomestatement.hs +++ b/Hledger/Cli/Commands/Incomestatement.hs @@ -1,4 +1,6 @@ -{-# LANGUAGE QuasiQuotes, TemplateHaskell, OverloadedStrings #-} +{-# LANGUAGE QuasiQuotes #-} +{-# LANGUAGE TemplateHaskell #-} +{-# LANGUAGE OverloadedStrings #-} {-| The @incomestatement@ command prints a simple income statement (profit & loss report). diff --git a/Hledger/Cli/Commands/Notes.hs b/Hledger/Cli/Commands/Notes.hs --- a/Hledger/Cli/Commands/Notes.hs +++ b/Hledger/Cli/Commands/Notes.hs @@ -16,7 +16,7 @@ ) where import Data.List.Extra (nubSort) -import qualified Data.Text.IO as T +import Data.Text.IO qualified as T import Hledger import Hledger.Cli.CliOptions diff --git a/Hledger/Cli/Commands/Payees.hs b/Hledger/Cli/Commands/Payees.hs --- a/Hledger/Cli/Commands/Payees.hs +++ b/Hledger/Cli/Commands/Payees.hs @@ -14,7 +14,7 @@ ,payees ) where -import qualified Data.Text.IO as T +import Data.Text.IO qualified as T import System.Console.CmdArgs.Explicit import Hledger diff --git a/Hledger/Cli/Commands/Prices.hs b/Hledger/Cli/Commands/Prices.hs --- a/Hledger/Cli/Commands/Prices.hs +++ b/Hledger/Cli/Commands/Prices.hs @@ -9,8 +9,8 @@ where import Data.List -import qualified Data.Text as T -import qualified Data.Text.IO as T +import Data.Text qualified as T +import Data.Text.IO qualified as T import Hledger import Hledger.Cli.CliOptions import System.Console.CmdArgs.Explicit diff --git a/Hledger/Cli/Commands/Print.hs b/Hledger/Cli/Commands/Print.hs --- a/Hledger/Cli/Commands/Print.hs +++ b/Hledger/Cli/Commands/Print.hs @@ -24,10 +24,10 @@ import Data.List.Extra (nubSort) import Data.Text (Text) import Data.Map (Map) -import qualified Data.Map as Map -import qualified Data.Text as T -import qualified Data.Text.Lazy as TL -import qualified Data.Text.Lazy.Builder as TB +import Data.Map qualified as Map +import Data.Text qualified as T +import Data.Text.Lazy qualified as TL +import Data.Text.Lazy.Builder qualified as TB import Lens.Micro ((^.), _Just, has) import Safe (lastMay, minimumDef) import System.Console.CmdArgs.Explicit @@ -37,12 +37,12 @@ import Hledger.Write.Csv (CSV, printCSV, printTSV) import Hledger.Write.Ods (printFods) import Hledger.Write.Html.Lucid (styledTableHtml) -import qualified Hledger.Write.Spreadsheet as Spr +import Hledger.Write.Spreadsheet qualified as Spr import Hledger.Cli.CliOptions import Hledger.Cli.Utils import Hledger.Cli.Anchor (setAccountAnchor) -import qualified Lucid -import qualified System.IO as IO +import Lucid qualified +import System.IO qualified as IO import Data.Maybe (isJust, catMaybes, fromMaybe) import Hledger.Write.Beancount (commodityToBeancount, tagsToBeancountMetadata) diff --git a/Hledger/Cli/Commands/Print.txt b/Hledger/Cli/Commands/Print.txt --- a/Hledger/Cli/Commands/Print.txt +++ b/Hledger/Cli/Commands/Print.txt @@ -52,7 +52,7 @@ expenses:supplies $1 assets:cash $-2 -print explicitness +print amount explicitness Normally, whether posting amounts are implicit or explicit is preserved. For example, when an amount is omitted in the journal, it will not @@ -69,50 +69,61 @@ implicit amount) to be split into multiple single-commodity postings, keeping the output parseable. -print amount style +print alignment Amounts are shown right-aligned within each transaction (but not aligned -across all transactions; you can do that with ledger-mode in Emacs). +across all transactions; you can achieve 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. +print amount style -With the --round (Added in 1.32) option, print will try increasingly -hard to display decimal digits according to the commodity display -styles: +Amounts will be displayed mostly in their commodity's display style, +with standardised symbol placement, decimal mark, and digit group marks. +This does not apply to their decimal digits; print normally shows the +same decimal digits that are recorded in each journal entry. +You can override the decimal precisions with print's special --round +option (since 1.32). --round tries to show amounts with their +commodities' standard decimal precisions, increasingly strongly: + - --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. +soft is good for non-lossy cleanup, displaying more consistent decimals +where possible, without making entries unbalanced. -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. +hard or all can be good for stronger cleanup, when decimal rounding is +wanted. Note rounding can produce unbalanced journal entries, perhaps +requiring manual fixup. 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): +Normally, print's output is a valid hledger journal, which you can +"pipe" to a second hledger command for further processing. This is +sometimes convenient for achieving certain kinds of query (though less +needed now that queries have become more powerful): # 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: +But here are some things which can cause print's output to 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. +- --round (see above) can disrupt transaction balancing. +- Account aliases or pivoting can disrupt account names, balance + assertions, or balance assignments. +- Value reporting also can disrupt balance assertions or balance + assignments. +- Auto postings can generate too many amountless postings. +- --infer-costs or --infer-equity can generate too-complex redundant + costs. +- Because print always shows transactions in date order, balance + assertions involving non-date-ordered transactions (and same-day + postings) could be disrupted. print, other features diff --git a/Hledger/Cli/Commands/Register.hs b/Hledger/Cli/Commands/Register.hs --- a/Hledger/Cli/Commands/Register.hs +++ b/Hledger/Cli/Commands/Register.hs @@ -21,27 +21,27 @@ import Data.Default (def) import Data.Maybe (fromMaybe, isJust) import Data.Text (Text) -import qualified Data.Map as Map -import qualified Data.Text as T -import qualified Data.Text.Lazy as TL -import qualified Data.Text.Lazy.IO as TL -import qualified Data.Text.Lazy.Builder as TB +import Data.Map qualified as Map +import Data.Text qualified as T +import Data.Text.Lazy qualified as TL +import Data.Text.Lazy.IO qualified as TL +import Data.Text.Lazy.Builder qualified as TB import System.Console.CmdArgs.Explicit (flagNone, flagReq) import Hledger hiding (per) import Hledger.Write.Csv (CSV, printCSV, printTSV) import Hledger.Write.Ods (printFods) import Hledger.Write.Html.Lucid (styledTableHtml) -import qualified Hledger.Write.Spreadsheet as Spr +import Hledger.Write.Spreadsheet qualified as Spr import Hledger.Cli.CliOptions import Hledger.Cli.Utils import Hledger.Cli.Anchor (setAccountAnchor, dateCell) import Text.Tabular.AsciiWide (Cell(..), Align(..), Properties(..), Header(Header, Group), renderRowB, textCell, tableBorders, borderSpaces) -import qualified Lucid +import Lucid qualified import Data.List (sortBy) import Data.Char (toUpper) import Data.List.Extra (intersect) -import qualified System.IO as IO +import System.IO qualified as IO registermode = hledgerCommandMode $(embedFileRelative "Hledger/Cli/Commands/Register.txt") diff --git a/Hledger/Cli/Commands/Rewrite.hs b/Hledger/Cli/Commands/Rewrite.hs --- a/Hledger/Cli/Commands/Rewrite.hs +++ b/Hledger/Cli/Commands/Rewrite.hs @@ -17,15 +17,15 @@ import Data.List (foldl') #endif import Data.Text (Text) -import qualified Data.Text as T -import qualified Data.Text.IO as T +import Data.Text qualified as T +import Data.Text.IO qualified as T import Hledger import Hledger.Cli.CliOptions import Hledger.Cli.Commands.Print import System.Console.CmdArgs.Explicit import Text.Printf import Text.Megaparsec hiding (pos1) -import qualified Data.Algorithm.Diff as D +import Data.Algorithm.Diff qualified as D rewritemode = hledgerCommandMode $(embedFileRelative "Hledger/Cli/Commands/Rewrite.txt") diff --git a/Hledger/Cli/Commands/Roi.hs b/Hledger/Cli/Commands/Roi.hs --- a/Hledger/Cli/Commands/Roi.hs +++ b/Hledger/Cli/Commands/Roi.hs @@ -23,8 +23,8 @@ import Data.List import Numeric.RootFinding import Data.Decimal -import qualified Data.Text as T -import qualified Data.Text.Lazy.IO as TL +import Data.Text qualified as T +import Data.Text.Lazy.IO qualified as TL import Safe (headDef) import System.Console.CmdArgs.Explicit as CmdArgs @@ -97,7 +97,7 @@ let (fullPeriodDateSpan, mspans) = reportSpan filteredj rspec let err = error' "Undefined start or end of the period - will be unable to compute the rates of return" - spans = maybe err (snd . periodDataToList) mspans + spans = maybe err (map (second (addDays 1)) . dayPartitionToList) mspans fullPeriod = case fullPeriodDateSpan of DateSpan (Just b) (Just e) -> (fromEFDay b, fromEFDay e) _ -> err diff --git a/Hledger/Cli/Commands/Run.hs b/Hledger/Cli/Commands/Run.hs --- a/Hledger/Cli/Commands/Run.hs +++ b/Hledger/Cli/Commands/Run.hs @@ -17,11 +17,11 @@ ,runOrReplStub ) where -import qualified Data.List.NonEmpty as NE -import qualified Data.Map.Strict as Map +import Data.List.NonEmpty qualified as NE +import Data.Map.Strict qualified as Map import Data.Semigroup (sconcat) -import qualified Data.Text as T -import qualified Data.Text.IO as T +import Data.Text qualified as T +import Data.Text.IO qualified as T import System.Console.CmdArgs.Explicit as C ( Mode ) import Hledger import Hledger.Cli.CliOptions @@ -160,7 +160,7 @@ then run (Just jpaths) findBuiltinCommand addons opts else cmdaction opts j Nothing | cmdname `elem` addons -> - system (printf "%s-%s %s" progname cmdname (unwords' args)) >>= exitWith + system (printf "%s-%s %s" progname cmdname (unwords $ map quoteForCommandLine args)) >>= exitWith Nothing -> error' $ "Unrecognized command: " ++ unwords (cmdname:args) [] -> return () diff --git a/Hledger/Cli/Commands/Setup.hs b/Hledger/Cli/Commands/Setup.hs --- a/Hledger/Cli/Commands/Setup.hs +++ b/Hledger/Cli/Commands/Setup.hs @@ -53,14 +53,14 @@ import Control.Exception import Control.Monad --- import qualified Data.ByteString as B +-- import Data.ByteString qualified as B import Data.Char import Data.Default (def) import Data.List -import qualified Data.Map as M +import Data.Map qualified as M import Data.Maybe -import qualified Data.Text as T -import qualified Data.Text.Encoding as T +import Data.Text qualified as T +import Data.Text.Encoding qualified as T import Network.HTTP.Client import Network.HTTP.Types (statusCode, hLocation) import Network.HTTP.Req as R @@ -358,7 +358,7 @@ -- i Y "" pdesc "a default journal file is readable ?" - jfile <- defaultJournalPath + ef <- defaultJournalPathSafely -- let -- args = concat [ -- ["print"], @@ -368,10 +368,12 @@ -- (exit, _, err) <- readProcessWithExitCode progname args "" -- XXX can this ignore assertions and config files, like the above ? ej <- defaultJournalSafely - case ej of - Left estr -> p N (jfile <> ":\n" <> estr) - Right j@Journal{..} -> do - p Y jfile + let trim s = either (const s) id $ regexReplace (toRegex' "^Error: ") "" s + case (ef, ej) of + (Left err, _) -> p N $ trim err + (Right f, Left err) -> p N (f <> ":\n" <> trim err) + (Right f, Right j@Journal{..}) -> do + p Y f pdesc "it includes additional files ?" let numfiles = length jfiles @@ -438,10 +440,10 @@ pdesc "all accounts have types ?" if null untypedaccts then p Y "" else i N (show (length untypedaccts) <> " accounts without types") - pdesc "all account types are detected ?" + pdesc "accounts of all types exist ?" if null typesnotfound - then p Y (concatMap show accttypes <> " account types detected") - else p N (concatMap show typesnotfound <> " not found; bs/cf/is reports may not work") + then p Y (concatMap show accttypes <> " accounts detected") + else p N (concatMap show typesnotfound <> " accounts not found; some reports may not work") pdesc "commodities/accounts are being checked ?" let strict = isJust $ conflookup (\a -> any (==a) ["-s", "--strict"]) diff --git a/Hledger/Cli/Commands/Stats.hs b/Hledger/Cli/Commands/Stats.hs --- a/Hledger/Cli/Commands/Stats.hs +++ b/Hledger/Cli/Commands/Stats.hs @@ -19,12 +19,12 @@ import System.FilePath (takeFileName) import Data.List (intercalate, nub, sortOn) import Data.List.Extra (nubSort) -import qualified Data.Map as Map +import Data.Map qualified as Map import Data.Maybe (fromMaybe) import Data.HashSet (size, fromList) -import qualified Data.Text as T -import qualified Data.Text.Lazy as TL -import qualified Data.Text.Lazy.Builder as TB +import Data.Text qualified as T +import Data.Text.Lazy qualified as TL +import Data.Text.Lazy.Builder qualified as TB import Data.Time.Calendar (Day, addDays, diffDays) import Data.Time.Clock.POSIX (getPOSIXTime) import GHC.Stats @@ -57,7 +57,7 @@ l = ledgerFromJournal q j intervalspans = snd $ reportSpanBothDates j rspec ismultiperiod = length intervalspans > 1 - (ls, txncounts) = unzip . map (showLedgerStats verbose l today) $ maybePeriodDataToDateSpans intervalspans + (ls, txncounts) = unzip . map (showLedgerStats verbose l today) $ maybeDayPartitionToDateSpans intervalspans numtxns = sum txncounts txt = (if ismultiperiod then id else TL.init) $ TB.toLazyText $ unlinesB ls writeOutputLazyText opts txt diff --git a/Hledger/Cli/Commands/Tags.hs b/Hledger/Cli/Commands/Tags.hs --- a/Hledger/Cli/Commands/Tags.hs +++ b/Hledger/Cli/Commands/Tags.hs @@ -8,10 +8,10 @@ ) where -import qualified Control.Monad.Fail as Fail +import Control.Monad.Fail qualified as Fail import Data.List.Extra (nubSort) -import qualified Data.Text as T -import qualified Data.Text.IO as T +import Data.Text qualified as T +import Data.Text.IO qualified as T import Safe import System.Console.CmdArgs.Explicit diff --git a/Hledger/Cli/CompoundBalanceCommand.hs b/Hledger/Cli/CompoundBalanceCommand.hs --- a/Hledger/Cli/CompoundBalanceCommand.hs +++ b/Hledger/Cli/CompoundBalanceCommand.hs @@ -19,16 +19,16 @@ import Data.Function ((&)) import Data.List.NonEmpty (NonEmpty((:|))) import Data.Maybe (fromMaybe, mapMaybe, maybeToList) -import qualified Data.Map as Map -import qualified Data.List as List -import qualified Data.List.NonEmpty as NonEmpty -import qualified Data.Text as T -import qualified Data.Text.Lazy as TL -import qualified Data.Text.Lazy.Builder as TB +import Data.Map qualified as Map +import Data.List qualified as List +import Data.List.NonEmpty qualified as NonEmpty +import Data.Text qualified as T +import Data.Text.Lazy qualified as TL +import Data.Text.Lazy.Builder qualified as TB import Data.Time.Calendar (Day, addDays) import Lucid as L hiding (Html, value_) import System.Console.CmdArgs.Explicit as C (Mode, flagNone, flagReq) -import qualified System.IO as IO +import System.IO qualified as IO import Text.Tabular.AsciiWide as Tabular hiding (render) import Hledger @@ -39,7 +39,7 @@ import Hledger.Write.Html (htmlAsLazyText, styledTableHtml, Html) import Hledger.Write.Html.Attribute (stylesheet, tableStyle, alignleft) import Hledger.Write.Ods (printFods) -import qualified Hledger.Write.Spreadsheet as Spr +import Hledger.Write.Spreadsheet qualified as Spr -- | Description of a compound balance report command, -- from which we generate the command's cmdargs mode and IO action. diff --git a/Hledger/Cli/Conf.hs b/Hledger/Cli/Conf.hs --- a/Hledger/Cli/Conf.hs +++ b/Hledger/Cli/Conf.hs @@ -26,10 +26,10 @@ import Control.Monad (void, forM) import Control.Monad.Identity (Identity) import Data.Functor ((<&>)) -import qualified Data.Map as M +import Data.Map qualified as M import Data.Maybe (catMaybes) import Data.Text (Text) -import qualified Data.Text as T (pack) +import Data.Text qualified as T (pack) import Safe (headMay, lastDef) import System.Directory (getHomeDirectory, getXdgDirectory, XdgDirectory (XdgConfig), doesFileExist, getCurrentDirectory) import System.FilePath ((), takeDirectory) diff --git a/Hledger/Cli/DocFiles.hs b/Hledger/Cli/DocFiles.hs --- a/Hledger/Cli/DocFiles.hs +++ b/Hledger/Cli/DocFiles.hs @@ -1,4 +1,7 @@ -{-# LANGUAGE TemplateHaskell, OverloadedStrings, PackageImports, ScopedTypeVariables #-} +{-# LANGUAGE OverloadedStrings #-} +{-# LANGUAGE PackageImports #-} +{-# LANGUAGE ScopedTypeVariables #-} +{-# LANGUAGE TemplateHaskell #-} {-| Embedded documentation files in various formats, and helpers for viewing them. @@ -18,7 +21,7 @@ import Control.Exception import Data.ByteString (ByteString) -import qualified Data.ByteString.Char8 as BC +import Data.ByteString.Char8 qualified as BC import Data.Maybe (fromMaybe) import Data.String import System.Environment (setEnv) diff --git a/Hledger/Cli/Script.hs b/Hledger/Cli/Script.hs --- a/Hledger/Cli/Script.hs +++ b/Hledger/Cli/Script.hs @@ -32,7 +32,7 @@ import "text" Data.Text as M (Text, pack, unpack) -- can't re-export much of Data.Text & Data.Text.IO, they need to be qualified import Safe as M hiding (at) --- import qualified System.Console.CmdArgs.Explicit as M +-- import System.Console.CmdArgs.Explicit qualified as M import System.Directory as M import System.Environment as M import System.Exit as M diff --git a/Hledger/Cli/Utils.hs b/Hledger/Cli/Utils.hs --- a/Hledger/Cli/Utils.hs +++ b/Hledger/Cli/Utils.hs @@ -32,13 +32,13 @@ import Control.Monad.Except (ExceptT) import Control.Monad.IO.Class (liftIO) import Data.List -import qualified Data.List.NonEmpty as NE (toList) +import Data.List.NonEmpty qualified as NE (toList) import Data.Maybe -import qualified Data.Text as T -import qualified Data.Text.IO as T -import qualified Data.Text.Lazy as TL -import qualified Data.Text.Lazy.Builder as TB -import qualified Data.Text.Lazy.IO as TL +import Data.Text qualified as T +import Data.Text.IO qualified as T +import Data.Text.Lazy qualified as TL +import Data.Text.Lazy.Builder qualified as TB +import Data.Text.Lazy.IO qualified as TL import Data.Time (Day) import Data.Time.Clock.POSIX (POSIXTime, utcTimeToPOSIXSeconds) import Lens.Micro ((^.)) diff --git a/Hledger/Cli/Version.hs b/Hledger/Cli/Version.hs --- a/Hledger/Cli/Version.hs +++ b/Hledger/Cli/Version.hs @@ -36,10 +36,10 @@ import Text.Megaparsec import Data.Void (Void) import Text.Megaparsec.Char -import qualified Text.Megaparsec.Char.Lexer as L +import Text.Megaparsec.Char.Lexer qualified as L import Hledger.Data.Dates (parsedate) import Data.Bifunctor -import qualified Data.List.NonEmpty as NE +import Data.List.NonEmpty qualified as NE -- | A Cabal/Hackage-compatible package version string: one or more dot-separated integers. diff --git a/app/hledger-cli.hs b/app/hledger-cli.hs --- a/app/hledger-cli.hs +++ b/app/hledger-cli.hs @@ -2,7 +2,7 @@ module Main (main) where -import qualified Hledger.Cli (main) +import Hledger.Cli qualified (main) -- Have to write this explicitly for GHC 9.0.1a for some reason: main :: IO () diff --git a/embeddedfiles/hledger-ui.1 b/embeddedfiles/hledger-ui.1 --- a/embeddedfiles/hledger-ui.1 +++ b/embeddedfiles/hledger-ui.1 @@ -1,5 +1,5 @@ -.TH "HLEDGER\-UI" "1" "September 2025" "hledger-ui-1.50.2 " "hledger User Manuals" +.TH "HLEDGER\-UI" "1" "November 2025" "hledger-ui-1.50.3 " "hledger User Manuals" @@ -17,7 +17,7 @@ .PD \f[CR]hledger ui [OPTS] [QUERYARGS]\f[R] .SH DESCRIPTION -This manual is for hledger\[aq]s terminal interface, version 1.50.2. +This manual is for hledger\[aq]s terminal interface, version 1.50.3. See also the hledger manual for common concepts and file formats. .PP hledger is a robust, user\-friendly, cross\-platform set of programs for @@ -250,6 +250,9 @@ \f[CR]I\f[R] toggles balance assertion checking. Disabling balance assertions temporarily can be useful for troubleshooting. +(If hledger\-ui was started with a \f[CR]\-\-pivot\f[R] option, +re\-enabling balance assertions with the \f[CR]I\f[R] key also reloads +the journal, like \f[CR]g\f[R].) .PP \f[CR]a\f[R] runs command\-line hledger\[aq]s add command, and reloads the updated file. @@ -441,10 +444,6 @@ On some unix systems, increasing fs.inotify.max_user_watches or fs.file\-max parameters in /etc/sysctl.conf might help. (#836) -.IP \[bu] 2 -It may not detect file changes made by certain tools, such as Jetbrains -IDEs or gedit. -(#1617) .IP \[bu] 2 It may not detect changes made from outside a virtual machine, ie by an editor running on the host system. diff --git a/embeddedfiles/hledger-ui.info b/embeddedfiles/hledger-ui.info --- a/embeddedfiles/hledger-ui.info +++ b/embeddedfiles/hledger-ui.info @@ -18,7 +18,7 @@ or 'hledger ui [OPTS] [QUERYARGS]' - This manual is for hledger's terminal interface, version 1.50.2. See + This manual is for hledger's terminal interface, version 1.50.3. See also the hledger manual for common concepts and file formats. hledger is a robust, user-friendly, cross-platform set of programs @@ -256,7 +256,9 @@ pause.) 'I' toggles balance assertion checking. Disabling balance assertions -temporarily can be useful for troubleshooting. +temporarily can be useful for troubleshooting. (If hledger-ui was +started with a '--pivot' option, re-enabling balance assertions with the +'I' key also reloads the journal, like 'g'.) 'a' runs command-line hledger's add command, and reloads the updated file. This allows some basic data entry. @@ -503,8 +505,6 @@ configuration. On some unix systems, increasing fs.inotify.max_user_watches or fs.file-max parameters in /etc/sysctl.conf might help. (#836) - * It may not detect file changes made by certain tools, such as - Jetbrains IDEs or gedit. (#1617) * It may not detect changes made from outside a virtual machine, ie by an editor running on the host system. * It may not detect file changes on certain less common filesystems. @@ -558,19 +558,19 @@ Node: OPTIONS1869 Node: MOUSE8755 Node: KEYS9087 -Node: SCREENS14091 -Node: Menu screen14831 -Node: Cash accounts screen15147 -Node: Balance sheet accounts screen15508 -Node: Income statement accounts screen15844 -Node: All accounts screen16229 -Node: Register screen16592 -Node: Transaction screen19035 -Node: Error screen20215 -Node: WATCH MODE20581 -Node: --watch problems21479 -Node: ENVIRONMENT22832 -Node: BUGS23065 +Node: SCREENS14229 +Node: Menu screen14969 +Node: Cash accounts screen15285 +Node: Balance sheet accounts screen15646 +Node: Income statement accounts screen15982 +Node: All accounts screen16367 +Node: Register screen16730 +Node: Transaction screen19173 +Node: Error screen20353 +Node: WATCH MODE20719 +Node: --watch problems21617 +Node: ENVIRONMENT22864 +Node: BUGS23097  End Tag Table diff --git a/embeddedfiles/hledger-ui.txt b/embeddedfiles/hledger-ui.txt --- a/embeddedfiles/hledger-ui.txt +++ b/embeddedfiles/hledger-ui.txt @@ -11,7 +11,7 @@ hledger ui [OPTS] [QUERYARGS] DESCRIPTION - This manual is for hledger's terminal interface, version 1.50.2. See + This manual is for hledger's terminal interface, version 1.50.3. See also the hledger manual for common concepts and file formats. hledger is a robust, user-friendly, cross-platform set of programs for @@ -223,7 +223,9 @@ pause.) I toggles balance assertion checking. Disabling balance assertions - temporarily can be useful for troubleshooting. + temporarily can be useful for troubleshooting. (If hledger-ui was + started with a --pivot option, re-enabling balance assertions with the + I key also reloads the journal, like g.) a runs command-line hledger's add command, and reloads the updated file. This allows some basic data entry. @@ -398,38 +400,35 @@ tify.max_user_watches or fs.file-max parameters in /etc/sysctl.conf might help. (#836) - o It may not detect file changes made by certain tools, such as Jet- - brains IDEs or gedit. (#1617) - - o It may not detect changes made from outside a virtual machine, ie by + o It may not detect changes made from outside a virtual machine, ie by an editor running on the host system. o It may not detect file changes on certain less common filesystems. - o It may use increasing CPU and RAM over time, especially with large - files. (This is probably not --watch specific, you may be able to + o It may use increasing CPU and RAM over time, especially with large + files. (This is probably not --watch specific, you may be able to reproduce it by pressing g repeatedly.) (#1825) Tips/workarounds: - o If --watch won't work for you, press g to reload data manually in- + o If --watch won't work for you, press g to reload data manually in- stead. - o If --watch is leaking resources over time, quit and restart (or sus- + o If --watch is leaking resources over time, quit and restart (or sus- pend and resume) hledger-ui when you're not using it. - o When running hledger-ui inside a VM, also make file changes inside + o When running hledger-ui inside a VM, also make file changes inside the VM. - o When working with files mounted from another machine, make sure the + o When working with files mounted from another machine, make sure the system clocks on both machines are roughly in agreement. 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 + We welcome bug reports in the hledger issue tracker (https://bugs.hledger.org), or on the hledger chat or mail list (https://hledger.org/support). @@ -437,7 +436,7 @@ -f- doesn't work (hledger-ui can't read from stdin). - --watch is not robust, especially with large files (see WATCH MODE + --watch is not robust, especially with large files (see WATCH MODE above). If you press g with large files, there could be a noticeable pause with @@ -461,4 +460,4 @@ SEE ALSO hledger(1), hledger-ui(1), hledger-web(1), ledger(1) -hledger-ui-1.50.2 September 2025 HLEDGER-UI(1) +hledger-ui-1.50.3 November 2025 HLEDGER-UI(1) diff --git a/embeddedfiles/hledger-web.1 b/embeddedfiles/hledger-web.1 --- a/embeddedfiles/hledger-web.1 +++ b/embeddedfiles/hledger-web.1 @@ -1,5 +1,5 @@ -.TH "HLEDGER\-WEB" "1" "September 2025" "hledger-web-1.50.2 " "hledger User Manuals" +.TH "HLEDGER\-WEB" "1" "November 2025" "hledger-web-1.50.3 " "hledger User Manuals" @@ -17,7 +17,7 @@ .PD \f[CR]hledger web [OPTS] [QUERY]\f[R] .SH DESCRIPTION -This manual is for hledger\[aq]s web interface, version 1.50.2. +This manual is for hledger\[aq]s web interface, version 1.50.3. See also the hledger manual for common concepts and file formats. .PP hledger is a robust, user\-friendly, cross\-platform set of programs for diff --git a/embeddedfiles/hledger-web.info b/embeddedfiles/hledger-web.info --- a/embeddedfiles/hledger-web.info +++ b/embeddedfiles/hledger-web.info @@ -18,7 +18,7 @@ or 'hledger web [OPTS] [QUERY]' - This manual is for hledger's web interface, version 1.50.2. See also + This manual is for hledger's web interface, version 1.50.3. See also the hledger manual for common concepts and file formats. hledger is a robust, user-friendly, cross-platform set of programs diff --git a/embeddedfiles/hledger-web.txt b/embeddedfiles/hledger-web.txt --- a/embeddedfiles/hledger-web.txt +++ b/embeddedfiles/hledger-web.txt @@ -11,7 +11,7 @@ hledger web [OPTS] [QUERY] DESCRIPTION - This manual is for hledger's web interface, version 1.50.2. See also + This manual is for hledger's web interface, version 1.50.3. See also the hledger manual for common concepts and file formats. hledger is a robust, user-friendly, cross-platform set of programs for @@ -480,4 +480,4 @@ SEE ALSO hledger(1), hledger-ui(1), hledger-web(1), ledger(1) -hledger-web-1.50.2 September 2025 HLEDGER-WEB(1) +hledger-web-1.50.3 November 2025 HLEDGER-WEB(1) diff --git a/embeddedfiles/hledger.1 b/embeddedfiles/hledger.1 --- a/embeddedfiles/hledger.1 +++ b/embeddedfiles/hledger.1 @@ -1,6 +1,6 @@ .\"t -.TH "HLEDGER" "1" "September 2025" "hledger-1.50.2 " "hledger User Manuals" +.TH "HLEDGER" "1" "November 2025" "hledger-1.50.3 " "hledger User Manuals" @@ -27,7 +27,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.50.2. +This manual is for hledger\[aq]s command line interface, version 1.50.3. 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! @@ -457,159 +457,140 @@ Below are more tips for using the command line interface \- feel free to skip these until you need them. .SS Special characters -Here we touch on shell escaping/quoting rules, and give some examples. -This is a slightly complicated topic which you may not need at first, -but you should be aware of it, so you can return here when needed. +In commands you type at the command line, certain characters have +special meaning and sometimes need to be \[dq]escaped\[dq] or +\[dq]quoted\[dq], by prefixing backslashes or enclosing in quotes. .PP If you are able to minimise the use of special characters in your data, -you won\[aq]t need escaping as much, and your command lines will be -simpler. -For example, avoiding spaces in account names, and using an ISO\-4217 -currency code like \f[CR]USD\f[R] instead of the \f[CR]$\f[R] currency -symbol, can be helpful. +you won\[aq]t have to deal with this as much. +For example, you could use hyphen \f[CR]\-\f[R] or underscore +\f[CR]_\f[R] instead of spaces in account names, and you could use the +\f[CR]USD\f[R] currency code instead of the \f[CR]$\f[R] currency symbol +in amounts. .PP -But if you want to use spaced account names and \f[CR]$\f[R], go right -ahead; escaping isn\[aq]t a big deal. +But if you prefer to use spaced account names and \f[CR]$\f[R], it\[aq]s +fine. +Just be aware of this topic so you can check this doc when needed. +(These examples are mostly tested on unix; some details might need to be +adapted if you\[aq]re on Windows.) .SS Escaping shell special characters -At the command line, characters which have special meaning for your -shell must be \[dq]shell\-escaped\[dq] (AKA \[dq]quoted\[dq]) if you -want hledger to see them. -Often these include space, \f[CR]<\f[R], \f[CR]>\f[R], \f[CR](\f[R], -\f[CR])\f[R], \f[CR]|\f[R], \f[CR]\[rs]\f[R], \f[CR]$\f[R] and/or -\f[CR]%\f[R]. +These are some characters which may have special meaning to your shell +(the program which interprets command lines): +.IP \[bu] 2 +SPACE, \f[CR]<\f[R], \f[CR]>\f[R], \f[CR](\f[R], \f[CR])\f[R], +\f[CR]|\f[R], \f[CR]\[rs]\f[R], \f[CR]%\f[R] +.IP \[bu] 2 +\f[CR]$\f[R] if followed by a word character .PP -For example, to match an account name containing the phrase \[dq]credit -card\[dq], don\[aq]t write this: +So for example, to match an account name containing spaces, like +\[dq]credit card\[dq], don\[aq]t write: .IP .EX $ hledger register credit card .EE .PP -In that command, \[dq]credit\[dq] and \[dq]card\[dq] are treated as -separate query arguments (described below), so this would match accounts -containing either word. -Instead, enclose the phrase in double or single quotes: +Instead, enclose the name in single quotes: .IP .EX -$ hledger register \[dq]credit card\[dq] +$ hledger register \[aq]credit card\[aq] .EE .PP -In Unix shells, writing a backslash before the character can also work. -Eg: +On unix or in Windows powershell, if you use double quotes your shell +will silently treat \f[CR]$\f[R] as variable interpolation. +So you should probably avoid double quotes, unless you want that +behaviour, eg in a script: .IP .EX -$ hledger register credit\[rs] card +$ hledger register \[dq]assets:$SOMEACCT\[dq] .EE .PP -Some shell characters still have a special meaning inside double quotes, -such as the dollar sign (\f[CR]$\f[R]). -Eg in \f[CR]\[dq]assets:$account\[dq]\f[R], the bash shell would replace -\f[CR]$account\f[R] with the value of a shell variable with that name. -When you don\[aq]t want that, use single quotes, which escape more -strongly: +But in an older Windows CMD.EXE window, you must use double quotes: .IP .EX -$ hledger balance \[aq]assets:$account\[aq] +C:\[rs]Users\[rs]Me> hledger register \[dq]credit card\[dq] .EE -.SS Escaping on Windows -If you are using hledger in a Powershell or Command window on Microsoft -Windows, the escaping rules are different: -.IP \[bu] 2 -In a Powershell window (\f[CR]powershell\f[R], blue background), you -must use double quotes or single quotes (not backslash). -.IP \[bu] 2 -In a Command window (\f[CR]cmd\f[R], black background), you must use -double quotes (not single quotes or backslash). .PP -The next two sections were written for Unix\-like shells, so might need -to be adapted if you\[aq]re using \f[CR]cmd\f[R] or -\f[CR]powershell\f[R]. -(Edits welcome.) -.SS Escaping regular expression special characters -Many hledger arguments are regular expressions (described below), and -these too have characters which cause special effects. -Some of those characters are \f[CR].\f[R], \f[CR]\[ha]\f[R], -\f[CR]$\f[R], \f[CR][\f[R], \f[CR]]\f[R], \f[CR](\f[R], \f[CR])\f[R], -\f[CR]|\f[R], and \f[CR]\[rs]\f[R]. -When you don\[aq]t want these to cause special effects, you can -\[dq]regex\-escape\[dq] them by writing \f[CR]\[rs]\f[R] (a backslash) -before them. -But since backslash is also special to the shell, you may need to also -shell\-escape the backslashes. -.PP -Eg, in the bash shell, to match a literal \f[CR]$\f[R] sign, you could -write: +On unix or in Windows powershell, as an alternative to quotes you can +write a backslash before each special character: .IP .EX -$ hledger balance cur:\[rs]\[rs]$ +$ hledger register credit\[rs] card .EE .PP -or: +Finally, since hledger\[aq]s query arguments are regular expressions +(described below), you could also fill that gap with \f[CR].\f[R] which +matches any character: .IP .EX -$ hledger balance \[aq]cur:\[rs]$\[aq] +$ hledger register credit.card .EE -.PP -(The dollar sign is regex\-escaped by the backslash preceding it. -Then that backslash is shell\-escaped by another backslash, or by single -quotes.) -.SS Escaping add\-on arguments -When you run an external add\-on command with \f[CR]hledger\f[R] -(described below), any options or arguments being passed through to the -add\-on executable lose one level of shell\-escaping, so you must add an -extra level of shell\-escaping to compensate. +.SS Escaping regular expression special characters +Some characters also have special meaning in regular expressions, which +hledger\[aq]s arguments often are. +Those include: +.IP \[bu] 2 +\f[CR].\f[R], \f[CR]\[ha]\f[R], \f[CR]$\f[R], \f[CR][\f[R], +\f[CR]]\f[R], \f[CR](\f[R], \f[CR])\f[R], \f[CR]|\f[R], \f[CR]\[rs]\f[R] .PP -Eg, in the bash shell, to run the \f[CR]ui\f[R] add\-on and match a -literal \f[CR]$\f[R] sign, you need to write: -.IP -.EX -$ hledger ui cur:\[aq]\[rs]\[rs]$\[aq] -.EE +To escape one of these, write \f[CR]\[rs]\f[R] before it. +But note this is in addition to the shell escaping above. +So for characters which are special to both shell and regular +expressions, like \f[CR]\[rs]\f[R] and \f[CR]$\f[R], you will sometimes +need two levels of escaping. .PP -or: +For example, a balance report that uses a \f[CR]cur:\f[R] query +restricting it to just the $ currency, should be written like this: .IP .EX -$ hledger ui cur:\[rs]\[rs]\[rs]\[rs]$ +$ hledger balance cur:\[rs]\[rs]$ .EE .PP -If you are wondering why \f[I]four\f[R] backslashes: -.IP \[bu] 2 -\f[CR]$\f[R] is unescaped -.IP \[bu] 2 -\f[CR]\[rs]$\f[R] is regex\-escaped -.IP \[bu] 2 -\f[CR]\[rs]\[rs]$\f[R] is regex\-escaped, then shell\-escaped -.IP \[bu] 2 -\f[CR]\[rs]\[rs]\[rs]\[rs]$\f[R] is regex\-escaped, then shell\-escaped, -then both slashes are shell\-escaped once more for hledger argument -pass\-through. +Explanation: +.IP "1." 3 +Add a backslash \f[CR]\[rs]\f[R] before the dollar sign \f[CR]$\f[R] to +protect it from regular expressions (so it will be matched literally +with no special meaning). +.IP "2." 3 +Add another backslash before that backslash, to protect it from the +shell (so the shell won\[aq]t consume it). +.IP "3." 3 +\f[CR]$\f[R] doesn\[aq]t need to be protected from the shell in this +case, because it\[aq]s not followed by a word character; but it would be +harmless to do so. .PP -Or you can avoid such triple\-escaping, by running the add\-on -executable directly: +But here\[aq]s another way to write that, which tends to be easier: add +backslashes to escape from regular expressions, then enclose with quotes +to escape from the shell: .IP .EX -$ hledger\-ui cur:\[rs]\[rs]$ +$ hledger balance cur:\[aq]\[rs]$\[aq] .EE .SS Escaping in other situations hledger options and arguments are sometimes used in places other than -the command line, with different escaping rules. -For example, backslash\-quoting generally does not work there. -Here are some more tips. +the command line, where the escaping/quoting rules are different. +For example, backslash\-quoting may not be available. +Here\[aq]s a quick reference: .PP .TS tab(@); lw(17.5n) lw(52.5n). T{ -In Windows \f[CR]cmd\f[R] +In unix shell T}@T{ -Use double quotes +Use single quotes and/or backslash (or double quotes for variable +interpolation) T} T{ In Windows \f[CR]powershell\f[R] T}@T{ -Use single or double quotes +Use single quotes (or double quotes for variable interpolation) T} T{ +In Windows \f[CR]cmd\f[R] +T}@T{ +Use double quotes +T} +T{ In hledger\-ui\[aq]s filter prompt T}@T{ Use single or double quotes @@ -622,14 +603,14 @@ T{ In an argument file T}@T{ -Don\[aq]t use spaces, don\[aq]t shell\-escape, do regex\-escape when -needed +Don\[aq]t use spaces, don\[aq]t shell\-escape, do regex\-escape, write +one argument/option per line T} T{ In a config file T}@T{ Use single or double quotes, and enclose the whole argument -(\f[CR]\[dq]desc:a b\[dq]\f[R] not \f[CR]desc:\[dq]a b\[dq]\f[R]) +(\f[CR]\[aq]desc:a b\[aq]\f[R] not \f[CR]desc:\[aq]a b\[aq]\f[R]) T} T{ In \f[CR]ghci\f[R] (the Haskell REPL) @@ -637,15 +618,6 @@ Use double quotes, and enclose the whole argument T} .TE -.SS Using a wild card -When escaping a special character is too much hassle (or impossible), -you can often just write \f[CR].\f[R] (period) instead. -In regular expressions, this means \[dq]accept any character here\[dq]. -Eg: -.IP -.EX -$ hledger register credit.card -.EE .SS Unicode characters hledger is expected to handle non\-ascii characters correctly: .IP \[bu] 2 @@ -806,17 +778,39 @@ See Special characters. .SS Argument files You can save a set of command line options and arguments in a file, and -then reuse them by writing \f[CR]\[at]FILENAME\f[R] as a command line +then use them by writing \f[CR]\[at]FILE.args\f[R] as a hledger command argument. -Eg: \f[CR]hledger bal \[at]foo.args\f[R]. +The \f[CR].args\f[R] file extension is conventional, but not required. +In an argument file, +.IP \[bu] 2 +Each line can contain one argument, flag, or option. +.IP \[bu] 2 +Blank lines or lines beginning with \f[CR]#\f[R] are ignored. +.IP \[bu] 2 +An option\[aq]s flag and value should be joined by \f[CR]=\f[R]. +.IP \[bu] 2 +An option value or an argument may contain spaces. +Don\[aq]t use single or double quotes. +.IP \[bu] 2 +And generally, use one less level of quoting/escaping than at the +command line. +Eg \f[CR]cur:\[rs]$\f[R], not \f[CR]cur:\[rs]\[rs]$\f[R] as on the +command line. .PP -An argument file\[aq]s format is more restrictive than the command line. -Each line should contain just one option or argument. -Don\[aq]t use spaces except inside quotes; write \f[CR]=\f[R] or nothing -between a flag and its argument. -If you use quotes, they must enclose the whole line. -For the special characters mentioned above, use one less level of -quoting than you would at the command line. +For example: +.IP +.EX +# cash.args + +assets:cash +assets:charles schwab:sweep +cur:\[rs]$ +\-c=$1. +.EE +.IP +.EX +$ hledger bal \[at]cash.args +.EE .SS Config files With hledger 1.40+, you can save extra command line options and arguments in a more featureful hledger config file. @@ -1127,7 +1121,7 @@ Multi\-period multi\-currency reports can often be wider than the window. Besides using a pager, helpful techniques for this situation include -\f[CR]\-\-layout=bare\f[R], \f[CR]\-V\f[R], \f[CR]cur:\f[R], +\f[CR]\-\-layout=bare\f[R], \f[CR]\-X COMM\f[R], \f[CR]cur:\f[R], \f[CR]\-\-transpose\f[R], \f[CR]\-\-tree\f[R], \f[CR]\-\-depth\f[R], \f[CR]\-\-drop\f[R], switching to html output, etc. .SS Box\-drawing characters @@ -1371,10 +1365,21 @@ specifies the \f[CR]less\f[R] options hledger should use. (Otherwise, \f[CR]LESS\f[R] + custom options are used.) .PP -\f[B]LEDGER_FILE\f[R] The main journal file to use when not specified -with \f[CR]\-f/\-\-file\f[R]. -Default: \f[CR]$HOME/.hledger.journal\f[R]. +\f[B]LEDGER_FILE\f[R] The default journal file, to be used when no +\f[CR]\-f/\-\-file\f[R] option is provided. +For example, it could be \f[CR]\[ti]/finance/main.journal\f[R]. +This can also be a glob pattern, eg \f[CR]./2???.journal\f[R]. +(If the glob matches multiple files, only the alphanumerically first one +is used.) +If LEDGER_FILE points to a non\-existent file, an error will be raised. +If the value is the empty string, it is ignored. .PP +If LEDGER_FILE is not set and \f[CR]\-f\f[R] is not provided, the +default journal file is \f[CR]$HOME/.hledger.journal\f[R] (or if a home +directory can\[aq]t be detected, \f[CR]./.hledger.journal\f[R]). +.PP +See also Common tasks > Setting LEDGER_FILE. +.PP \f[B]NO_COLOR\f[R] If this environment variable exists (with any value, including empty), hledger will not use ANSI color codes in terminal output, unless overridden by an explicit \f[CR]\-\-color=y\f[R] or @@ -4179,9 +4184,9 @@ declare the field separator, instead of relying on file extension T} T{ -\f[B]\f[CB]skip\f[B]\f[R] +\f[B]\f[CB]decimal\-mark\f[B]\f[R] T}@T{ -skip one or more header lines at start of file +declare the decimal mark used in CSV amounts, when ambiguous T} T{ \f[B]\f[CB]date\-format\f[B]\f[R] @@ -4206,9 +4211,9 @@ overall file T} T{ -\f[B]\f[CB]decimal\-mark\f[B]\f[R] +\f[B]\f[CB]skip\f[B]\f[R] T}@T{ -declare the decimal mark used in CSV amounts, when ambiguous +(at top level) skip header line(s) at start of file T} T{ \f[B]\f[CB]fields\f[B] list\f[R] @@ -4233,6 +4238,16 @@ conditionally assign values to hledger fields, using compact syntax T} T{ +\f[B]\f[CB]skip\f[B]\f[R] +T}@T{ +(inside an \f[CR]if\f[R] rule) skip current record(s) +T} +T{ +\f[B]\f[CB]end\f[B]\f[R] +T}@T{ +(inside an \f[CR]if\f[R] rule) skip all remaining records +T} +T{ \f[B]\f[CB]balance\-type\f[B]\f[R] T}@T{ select which type of balance assertions/assignments to generate @@ -4289,9 +4304,9 @@ files, then run \f[CR]hledger import rules/*\f[R]. .PP See also \[dq]Working with CSV > Reading files specified by rule\[dq]. -.SS Data cleaning / generating commands +.SS Data cleaning / data generating commands After \f[CR]source\f[R]\[aq]s file pattern, you can write \f[CR]|\f[R] -(pipe) and a data cleaning command. +(pipe) and a data cleaning command (or command pipeline). If hledger\[aq]s CSV rules aren\[aq]t enough, you can pre\-process the downloaded data here with a shell command or script, to make it more suitable for conversion. @@ -6689,18 +6704,17 @@ T} .TE .SH Depth -With the \f[CR]\-\-depth NUM\f[R] option (short form: \f[CR]\-NUM\f[R]), -reports will show accounts only to the specified depth, hiding deeper -subaccounts. +With the \f[CR]\-\-depth NUM\f[R] option (short form, usually preferred: +\f[CR]\-NUM\f[R]), reports will show accounts only to the specified +depth, hiding deeper subaccounts. Use this when you want a summary with less detail. This flag has the same effect as a \f[CR]depth:\f[R] query argument. So all of these are equivalent: \f[CR]depth:2\f[R], \f[CR]\-\-depth=2\f[R], \f[CR]\-2\f[R]. .PP -In place of a single number which limits the depth for all accounts, you -can also provide depth limits for specific accounts, by providing a -\f[CR]REGEX=DEPTH\f[R] argument instead of just a \f[CR]DEPTH\f[R] -\f[I](since 1.41)\f[R]. +You can also provide custom depths for specific accounts, by providing a +\f[CR]REGEX=NUM\f[R] argument instead of just \f[CR]NUM\f[R] \f[I](since +1.41)\f[R]. For example, \f[CR]\-\-depth assets=2\f[R] (or \f[CR]depth:assets=2\f[R]) will collapse accounts matching the regular expression \[dq]assets\[dq] to depth 2. @@ -6708,22 +6722,32 @@ \f[CR]assets:bank\f[R], but \f[CR]liabilities:bank:credit card\f[R] would not be affected. .PP -(If REGEX contains spaces or other special characters, enclose it in +If REGEX contains spaces or other special characters, enclose it in quotes in the usual way. -Eg: \f[CR]\-\-depth \[aq]credit card=2\[aq]\f[R]) +Eg: \f[CR]\-\-depth \[aq]credit card=2\[aq]\f[R] +.SS Combining depth options +If a command line contains multiple general depth options, the last one +wins. +(Useful for overriding a depth specified by scripts.) .PP -Specific depth options and a general depth option can be combined. -Eg \f[CR]\-\-depth assets=3 \-\-depth expenses=2 \-\-depth 1\f[R] would +Or a command may contain a combination of general and custom depth +options. +In this case, the most specifically (deepest) matching option wins. +Some examples: +.IP \[bu] 2 +\f[CR]\-\-depth assets=3 \-\-depth expenses=2 \-\-depth 1\f[R] would collapse accounts containing \[dq]assets\[dq] to depth 3, accounts containing \[dq]expenses\[dq] to depth 2, and all other accounts to depth 1. +.IP \[bu] 2 +\f[CR]\-\-depth assets=1 \-\-depth savings=2\f[R] would collapse +\f[CR]assets:bank:savings\f[R] to depth 2 (not depth 1; because +\[dq]savings\[dq] matches a deeper part of the account name than +\[dq]assets\[dq]). .PP -If an account is matched by more than one regular expression depth -argument, the most specific (deepest) match will be used. -For example, with \f[CR]\-\-depth assets=1 \-\-depth savings=2\f[R], -\f[CR]assets:bank:savings\f[R] will be collapsed to depth 2, not depth 1 -(because \[dq]savings\[dq] matches a deeper part of it than -\[dq]assets\[dq] does). +Note currently, to override a custom depth option +\f[CR]\-\-depth REGEX=NUM\f[R] with a later option, the later option +must use the same REGEX. .SH Queries Many hledger commands accept query arguments, which restrict their scope and let you report on a precise subset of your data. @@ -7878,15 +7902,43 @@ The market prices are declared with a special \f[CR]P\f[R] directive, and/or they can be inferred from the costs recorded in transactions, by using the \f[CR]\-\-infer\-market\-prices\f[R] flag. -.SS \-V: Value -The \f[CR]\-V/\-\-market\f[R] flag converts amounts to market value in -their default \f[I]valuation commodity\f[R], using the market prices in -effect on the \f[I]valuation date(s)\f[R], if any. -More on these in a minute. .SS \-X: Value in specified commodity -The \f[CR]\-X/\-\-exchange=COMM\f[R] option is like \f[CR]\-V\f[R], -except you tell it which currency you want to convert to, and it tries -to convert everything to that. +The \f[CR]\-X COMM\f[R] (or \f[CR]\-\-exchange=COMM\f[R]) option +converts amounts to their market value in the specified commodity, using +the market prices in effect on the \f[I]valuation date(s)\f[R], if any. +(More on these in a minute.) +.PP +Use this when you want to (eg) show everything in your base currency as +far as possible. +(Commodities for which no conversion rate can be found, will not be +converted.) +.PP +COMM should be the full commodity symbol or name. +Remember to quote special shell characters, if needed. +Some examples: +.IP \[bu] 2 +\f[CR]\-X€\f[R] +.IP \[bu] 2 +\f[CR]\-X$\f[R] (nothing after $, no quoting needed) +.IP \[bu] 2 +\f[CR]\-X CNY\f[R] (the space after \-X is optional) +.IP \[bu] 2 +\f[CR]\-X \[aq]red apples\[aq]\f[R] +.IP \[bu] 2 +\f[CR]\-X \[aq]r&r\[aq]\f[R] +.SS \-V: Value in default commodity(s) +The \f[CR]\-V/\-\-market\f[R] flag is a variant of \f[CR]\-X\f[R] where +you don\[aq]t have to specify COMM. +Instead it tries to guess a \f[I]default valuation commodity\f[R] for +each original commodity, based on the market prices in effect on the +valuation date(s). +.PP +\f[CR]\-V\f[R] can often be a convenient shortcut for +\f[CR]\-X MYCURRENCY\f[R], but not always; depending on your data it +could guess multiple valuation commodities. +Usually you want to convert to a single commodity, so it\[aq]s better to +use \f[CR]\-X\f[R], unless you\[aq]re sure \f[CR]\-V\f[R] is doing what +you want. .SS Valuation date Market prices can change from day to day. hledger will use the prices on a particular valuation date (or on more @@ -9075,27 +9127,29 @@ .PP There is a detailed tutorial at https://hledger.org/add.html. .SS add and balance assertions -Since hledger 1.43, whenever you enter a posting amount, \f[CR]add\f[R] -will re\-check all balance assertions in the journal, and if any of them -fail, it will report the problem and ask for the amount again. -.PP -You can also add a new balance assertion, following the amount as in -journal format. +Since hledger 1.43, you can add a balance assertion by writing +\f[CR]AMOUNT = BALANCE\f[R] when asked for an amount. +Eg \f[CR]100 = 500\f[R]. .PP -The new transaction\[aq]s date, and the new posting\[aq]s posting date -if any (entered in a comment following the amount), will influence +Also, each time you enter a new amount, hledger re\-checks all balance +assertions in the journal and rejects the new amount if it would make +any of them fail. +You can run \f[CR]add\f[R] with +\f[CR]\-I\f[R]/\f[CR]\-\-ignore\-assertions\f[R] to disable balance assertion checking. -.PP -You can use \f[CR]\-I\f[R]/\f[CR]\-\-ignore\-assertions\f[R] to disable -assertion checking temporarily. .SS add and balance assignments -Balance assignments are not recalculated during a \f[CR]hledger add\f[R] -session. -When \f[CR]add\f[R] runs, it sees the journal with all balance -assignments already processed and converted to assertions. -So if you add a new posting which is dated earlier than a balance -assignment, it will break the assertion and be rejected. -You can make it work by using \f[CR]hledger add \-I\f[R]. +Since hledger 1.50.3, you can add a balance assignment by writing +\f[CR]= BALANCE\f[R] (or \f[CR]==\f[R], \f[CR]=*\f[R] etc) when asked +for an amount. +The missing amount will be calculated automatically. +.PP +\f[CR]add\f[R] normally won\[aq]t let you add a new posting which is +dated earlier than an existing balance assignment. +(Because when \f[CR]add\f[R] runs, existing balance assignments have +already been calculated and converted to amounts and balance +assertions.) +You can allow it by disabling balance assertion checking with +\f[CR]\-I\f[R]. .SS import Import new transactions from one or more data files to the main journal. .IP @@ -9749,7 +9803,7 @@ expenses:supplies $1 assets:cash $\-2 .EE -.SS print explicitness +.SS print amount 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. @@ -9767,19 +9821,20 @@ with a multi\-commodity amount (which can arise when a multi\-commodity transaction has an implicit amount) to be split into multiple single\-commodity postings, keeping the output parseable. -.SS print amount style +.SS print alignment Amounts are shown right\-aligned within each transaction (but not -aligned across all transactions; you can do that with ledger\-mode in -Emacs). -.PP -Amounts will be (mostly) normalised to their commodity display style: -their symbol placement, decimal mark, and digit group marks will be made -consistent. -By default, decimal digits are shown as they are written in the journal. +aligned across all transactions; you can achieve that with ledger\-mode +in Emacs). +.SS print amount style +Amounts will be displayed mostly in their commodity\[aq]s display style, +with standardised symbol placement, decimal mark, and digit group marks. +This does not apply to their decimal digits; \f[CR]print\f[R] normally +shows the same decimal digits that are recorded in each journal entry. .PP -With the \f[CR]\-\-round\f[R] (\f[I]Added in 1.32\f[R]) option, -\f[CR]print\f[R] will try increasingly hard to display decimal digits -according to the commodity display styles: +You can override the decimal precisions with \f[CR]print\f[R]\[aq]s +special \f[CR]\-\-round\f[R] option (\f[I]since 1.32\f[R]). +\f[CR]\-\-round\f[R] tries to show amounts with their commodities\[aq] +standard decimal precisions, increasingly strongly: .IP \[bu] 2 \f[CR]\-\-round=none\f[R] show amounts with original precisions (default) @@ -9792,17 +9847,18 @@ .IP \[bu] 2 \f[CR]\-\-round=all\f[R] round all amounts and costs .PP -\f[CR]soft\f[R] is good for non\-lossy cleanup, formatting amounts more -consistently where it\[aq]s safe to do so. +\f[CR]soft\f[R] is good for non\-lossy cleanup, displaying more +consistent decimals where possible, without making entries unbalanced. .PP -\f[CR]hard\f[R] and \f[CR]all\f[R] can cause \f[CR]print\f[R] to show -invalid unbalanced journal entries; they may be useful eg for stronger -cleanup, with manual fixups when needed. +\f[CR]hard\f[R] or \f[CR]all\f[R] can be good for stronger cleanup, when +decimal rounding is wanted. +Note rounding can produce unbalanced journal entries, perhaps requiring +manual fixup. .SS print parseability -print\[aq]s output is usually a valid hledger journal, and you can -process it again with a second hledger command. -This can be useful for certain kinds of search (though the same can be -achieved with \f[CR]expr:\f[R] queries now): +Normally, print\[aq]s output is a valid hledger journal, which you can +\[dq]pipe\[dq] to a second hledger command for further processing. +This is sometimes convenient for achieving certain kinds of query +(though less needed now that queries have become more powerful): .IP .EX # Show running total of food expenses paid from cash. @@ -9810,15 +9866,25 @@ $ hledger print assets:cash | hledger \-f\- \-I reg expenses:food .EE .PP -There are some situations where print\[aq]s output can become +But here are some things which can cause print\[aq]s output to become unparseable: .IP \[bu] 2 -Value reporting affects posting amounts but not balance assertion or -balance assignment amounts, potentially causing those to fail. +\f[CR]\-\-round\f[R] (see above) can disrupt transaction balancing. .IP \[bu] 2 -Auto postings can generate postings with too many missing amounts. +Account aliases or pivoting can disrupt account names, balance +assertions, or balance assignments. .IP \[bu] 2 -Account aliases can generate bad account names. +Value reporting also can disrupt balance assertions or balance +assignments. +.IP \[bu] 2 +Auto postings can generate too many amountless postings. +.IP \[bu] 2 +\f[CR]\-\-infer\-costs or \-\-infer\-equity\f[R] can generate +too\-complex redundant costs. +.IP \[bu] 2 +Because print always shows transactions in date order, balance +assertions involving non\-date\-ordered transactions (and same\-day +postings) could be disrupted. .SS print, other features With \f[CR]\-B\f[R]/\f[CR]\-\-cost\f[R], amounts with costs are shown converted to cost. @@ -9957,9 +10023,12 @@ This is a more \[dq]real world\[dq], bank\-like view than the \f[CR]register\f[R] command (which shows individual postings, possibly from multiple accounts, not necessarily in historical mode). -As a quick rule of thumb: \- use \f[CR]aregister\f[R] for reviewing and -reconciling real\-world asset/liability accounts \- use -\f[CR]register\f[R] for reviewing detailed revenues/expenses. +As a quick rule of thumb: +.IP \[bu] 2 +\f[CR]aregister\f[R] is best when reconciling real\-world +asset/liability accounts +.IP \[bu] 2 +\f[CR]register\f[R] is best when reviewing individual revenues/expenses. .PP \f[CR]aregister\f[R] requires one argument: the account to report on. You can write either the full account name, or a case\-insensitive @@ -12101,9 +12170,21 @@ .EE .PP \f[CR]close\f[R] has six modes, selected by choosing one of the mode -flags (\f[CR]\-\-close\f[R] is the default). -They all do much the same operation, but with different defaults, useful -in different situations. +flags: \f[CR]\-\-clopen\f[R], \f[CR]\-\-close\f[R] (default), +\f[CR]\-\-open\f[R], \f[CR]\-\-assert\f[R], \f[CR]\-\-assign\f[R], or +\f[CR]\-\-retain\f[R]. +They are all doing the same kind of operation, but with different +defaults for different situations. +.PP +The journal entries generated by \f[CR]close\f[R] will have a +\f[CR]clopen:\f[R] tag, which is helpful when you want to exclude them +from reports. +If the main journal file name contains a number, the tag\[aq]s value +will be that base file name with the number incremented. +Eg if the journal file is 2025.journal, the tag will be +\f[CR]clopen:2026\f[R]. +Or you can set the tag value by providing an argument to the mode flag. +Eg \f[CR]\-\-close=foo\f[R] or \f[CR]\-\-clopen=2025\-main\f[R]. .SS close \-\-clopen This is useful if migrating balances to a new journal file at the start of a new year. @@ -12148,13 +12229,6 @@ .PP Assertions will be added indicating and checking the new balances of the closed/opened accounts. -.PP -The generated transactions will have a \f[CR]clopen:\f[R] tag. -If the main journal\[aq]s base file name contains a number (eg a year -number), the tag\[aq]s value will be that base file name with the number -incremented. -Or you can choose the tag value yourself, by using -\f[CR]\-\-clopen=TAGVAL\f[R]. .SS close \-\-close This prints just the closing balances transaction of \f[CR]\-\-clopen\f[R]. @@ -12206,16 +12280,16 @@ .IP \[bu] 2 the accounts to be closed/opened, with account query arguments .IP \[bu] 2 +the closing/opening dates, with \f[CR]\-e OPENDATE\f[R] +.IP \[bu] 2 the balancing account, with \f[CR]\-\-close\-acct=ACCT\f[R] and/or \f[CR]\-\-open\-acct=ACCT\f[R] .IP \[bu] 2 the transaction descriptions, with \f[CR]\-\-close\-desc=DESC\f[R] and \f[CR]\-\-open\-desc=DESC\f[R] .IP \[bu] 2 -the transaction\[aq]s tag value, with a \f[CR]\-\-MODE=NEW\f[R] option -argument -.IP \[bu] 2 -the closing/opening dates, with \f[CR]\-e OPENDATE\f[R] +the transactions\[aq] \f[CR]clopen\f[R] tag value, with a +\f[CR]TAGVAL\f[R] argument for the mode flag (see above). .PP By default, the closing date is yesterday, or the journal\[aq]s end date, whichever is later; and the opening date is always one day after @@ -12513,8 +12587,8 @@ run these checks, providing instant feedback as you edit the journal. .PP Here are the checks currently available. -Generally, they are performed in the order they are shown here (and only -the first failure is reported). +They are generally checked in the order they are shown here, and only +the first failure will be reported. .SS Basic checks These important checks are performed by default, by almost all hledger commands: @@ -12526,32 +12600,31 @@ \f[B]autobalanced\f[R] \- all transactions are balanced, after automatically inferring missing amounts and conversion rates and then converting amounts to cost. -This ensures that each transaction\[aq]s entry is well formed. +This ensures that each transaction\[aq]s journal entry is well formed. .IP \[bu] 2 \f[B]assertions\f[R] \- all balance assertions in the journal are passing. -Balance assertions are a strong defense against errors; they help catch -many problems. -If this check gets in your way, you can disable it with -\f[CR]\-I\f[R]/\f[CR]\-\-ignore\-assertions\f[R]. -Or you can add that to your config file to disable it by default (and -then use \f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R] or -\f[CR]hledger check assertions\f[R] to enable it). +Balance assertions are a strong defense against errors, catching many +problems. +This check is on by default, but if it gets in your way, you can disable +it temporarily with \f[CR]\-I\f[R]/\f[CR]\-\-ignore\-assertions\f[R], or +as a default by adding that flag to your config file. +(Then use \f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R] or +\f[CR]hledger check assertions\f[R] when you want to enable it). .SS Strict checks -These additional checks are performed by all commands when the -\f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R] flag is used (strict mode). -They provide extra error\-catching power to keep your data clean and -correct. -Strict mode also always enables the \f[CR]assertions\f[R] check. +When the \f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R] flag is used (AKA strict +mode), all commands will perform the following additional checks (and +\f[CR]assertions\f[R], above). +These provide extra error\-catching power to help you keep your data +clean and correct: .IP \[bu] 2 -\f[B]balanced\f[R] \- like \f[CR]autobalanced\f[R], but all conversions -between commodities must use explicit cost notation or equity postings. +\f[B]balanced\f[R] \- like \f[CR]autobalanced\f[R], but implicit +conversions between commodities are not allowed; all conversion +transactions must use cost notation or equity postings. This prevents wrong conversions caused by typos. .IP \[bu] 2 \f[B]commodities\f[R] \- all commodity symbols used must be declared. This guards against mistyping or omitting commodity symbols. -Declaring commodities also sets their precision for display and -transaction balancing. .IP \[bu] 2 \f[B]accounts\f[R] \- all account names used must be declared. This prevents the use of mis\-spelled or outdated account names. @@ -12580,10 +12653,10 @@ asset/liability accounts, which in turn should encourage you to reconcile regularly with those real world balances \- another strong defense against errors. -\f[CR]hledger close \-\-assert\f[R] can help generate assertion entries. -Over time the older assertions become somewhat redundant, and you can -remove them if you like (they don\[aq]t affect performance much, but -they add some noise to the journal). +(\f[CR]hledger close \-\-assert >>$LEDGER_FILE\f[R] is a convenient way +to add new balance assertions. +Later these become quite redundant, and you might choose to remove them +to reduce clutter.) .IP \[bu] 2 \f[B]uniqueleafnames\f[R] \- no two accounts may have the same last account name part (eg the \f[CR]checking\f[R] in @@ -12595,8 +12668,8 @@ See also Cookbook > Scripting. Here are some examples from hledger/bin/: .IP \[bu] 2 -\f[B]hledger\-check\-tagfiles\f[R] \- all tag values containing / (a -forward slash) exist as file paths +\f[B]hledger\-check\-tagfiles\f[R] \- all tag values containing +\f[CR]/\f[R] exist as file paths .IP \[bu] 2 \f[B]hledger\-check\-fancyassertions\f[R] \- more complex balance assertions are passing diff --git a/embeddedfiles/hledger.info b/embeddedfiles/hledger.info --- a/embeddedfiles/hledger.info +++ b/embeddedfiles/hledger.info @@ -24,13417 +24,13456 @@ and largely compatible with ledger(1), and largely interconvertible with beancount(1). - This manual is for hledger's command line interface, version 1.50.2. -It also describes the common options, file formats and concepts used by -all hledger programs. It might accidentally teach you some -bookkeeping/accounting as well! You don't need to know everything in -here to use hledger productively, but when you have a question about -functionality, this doc should answer it. It is detailed, so do skip -ahead or skim when needed. You can read it on hledger.org, or as an -info manual or man page on your system. You can also open a built-in -copy, at a point of interest, by running -'hledger --man [CMD]', 'hledger --info [CMD]' or 'hledger help [TOPIC]'. - - (And for shorter help, try 'hledger --tldr [CMD]'.) - - The main function of the hledger CLI is to read plain text files -describing financial transactions, crunch the numbers, and print a -useful report on the terminal (or save it as HTML, CSV, JSON or SQL). -Many reports are available, as subcommands. hledger will also detect -other 'hledger-*' executables as extra subcommands. - - hledger usually reads from (and appends to) a journal file specified -by the 'LEDGER_FILE' environment variable (defaulting to -'$HOME/.hledger.journal'); or you can specify files with '-f' options. -It can also read timeclock files, timedot files, or any CSV/SSV/TSV file -with a date field. - - Here is a small journal file describing one transaction: - -2015-10-16 bought food - expenses:food $10 - assets:cash - - Transactions are dated movements of money (etc.) between two or more -_accounts_: bank accounts, your wallet, revenue/expense categories, -people, etc. You can choose any account names you wish, using ':' to -indicate subaccounts. There must be at least two spaces between account -name and amount. Positive amounts are inflow to that account (_debit_), -negatives are outflow from it (_credit_). (Some reports show revenue, -liability and equity account balances as negative numbers as a result; -this is normal.) - - hledger's add command can help you add transactions, or you can -install other data entry UIs like hledger-web or hledger-iadd. For more -extensive/efficient changes, use a text editor: Emacs + ledger-mode, VIM -+ vim-ledger, or VS Code + hledger-vscode are some good choices (see -https://hledger.org/editors.html). - - To get started, run 'hledger add' and follow the prompts, or save -some entries like the above in '$HOME/.hledger.journal', then try -commands like: - -$ hledger print -x -$ hledger aregister assets -$ hledger balance -$ hledger balancesheet -$ hledger incomestatement - - Run 'hledger' to list the commands. See also the "Starting a journal -file" and "Setting opening balances" sections in PART 5: COMMON TASKS. - -* Menu: - -* PART 1 USER INTERFACE:: -* Input:: -* Commands:: -* Options:: -* Output:: -* Environment:: -* PART 2 DATA FORMATS:: -* Journal:: -* CSV:: -* Timeclock:: -* Timedot:: -* PART 3 REPORTING CONCEPTS:: -* Time periods:: -* Depth:: -* Queries:: -* Pivoting:: -* Generating data:: -* Forecasting:: -* Budgeting:: -* Amount formatting:: -* Cost reporting:: -* Value reporting:: -* PART 4 COMMANDS:: -* Help commands:: -* User interface commands:: -* Data entry commands:: -* Basic report commands:: -* Standard report commands:: -* Advanced report commands:: -* Chart commands:: -* Data generation commands:: -* Maintenance commands:: -* PART 5 COMMON TASKS:: -* Getting help:: -* Constructing command lines:: -* Starting a journal file:: -* Setting LEDGER_FILE:: -* Setting opening balances:: -* Recording transactions:: -* Reconciling:: -* Reporting:: -* Migrating to a new file:: -* BUGS:: - - -File: hledger.info, Node: PART 1 USER INTERFACE, Next: Input, Prev: Top, Up: Top - -1 PART 1: USER INTERFACE -************************ - - -File: hledger.info, Node: Input, Next: Commands, Prev: PART 1 USER INTERFACE, Up: Top - -2 Input -******* - -hledger reads one or more data files, each time you run it. You can -specify a file with '-f', like so - -$ hledger -f FILE [-f FILE2 ...] print - - Files are most often in hledger's journal format, with the '.journal' -file extension ('.hledger' or '.j' also work); these files describe -transactions, like an accounting general journal. - - When no file is specified, hledger looks for '.hledger.journal' in -your home directory. - - But most people prefer to keep financial files in a dedicated folder, -perhaps with version control. Also, starting a new journal file each -year is common (it's not required, but helps keep things fast and -organised). So we usually configure a different journal file, by -setting the 'LEDGER_FILE' environment variable, to something like -'~/finance/2023.journal'. For more about how to do that on your system, -see Common tasks > Setting LEDGER_FILE. - -* Menu: - -* Text encoding:: -* Data formats:: -* Standard input:: -* Multiple files:: -* Strict mode:: - - -File: hledger.info, Node: Text encoding, Next: Data formats, Up: Input - -2.1 Text encoding -================= - -hledger expects non-ascii input to be decodable with the system locale's -text encoding. (For CSV/SSV/TSV files, this can be overridden by the -'encoding' CSV rule.) - - So, trying to read non-ascii files which have the wrong text -encoding, or when no system locale is configured, will fail. To fix -this, configure your system locale appropriately, and/or convert the -files to your system's text encoding (using 'iconv' on unix, or -powershell or notepad on Windows). See Install: Text encoding for more -tips. - - hledger's output will use the system locale's encoding. - - hledger's docs and example files mostly use UTF-8 encoding. - - -File: hledger.info, Node: Data formats, Next: Standard input, Prev: Text encoding, Up: Input - -2.2 Data formats -================ - -Usually the data file is in hledger's journal format, but it can be in -any of the supported file formats, which currently are: - -Reader: Reads: Automatically used for - files with extensions: ---------------------------------------------------------------------------- -'journal' hledger journal files and some '.journal' '.j' - Ledger journals, for '.hledger' '.ledger' - transactions -'timeclock' timeclock files, for precise '.timeclock' - time logging -'timedot' timedot files, for approximate '.timedot' - time logging -'csv' Comma- or other '.csv' - delimiter-separated values, for - data import -'ssv' Semicolon separated values '.ssv' -'tsv' Tab separated values '.tsv' -'rules' CSV/SSV/TSV/other separated '.rules' - values, alternate way - - These formats are described in more detail below. - - hledger detects the format automatically based on the file extensions -shown above. If it can't recognise the file extension, it assumes -'journal' format. So for non-journal files, it's important to use a -recognised file extension, so as to either read successfully or to show -relevant error messages. - - You can also force a specific reader/format by prefixing the file -path with the format and a colon. Eg, to read a .dat file containing -tab separated values: - -$ hledger -f tsv:/some/file.dat stats - - -File: hledger.info, Node: Standard input, Next: Multiple files, Prev: Data formats, Up: Input - -2.3 Standard input -================== - -The file name '-' means standard input: - -$ cat FILE | hledger -f- print - - If reading non-journal data in this way, you'll need to write the -format as a prefix, like 'timeclock:' here: - -$ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:- - - -File: hledger.info, Node: Multiple files, Next: Strict mode, Prev: Standard input, Up: Input - -2.4 Multiple files -================== - -You can specify multiple '-f' options, to read multiple files as one big -journal. When doing this, note that certain features (described below) -will be affected: - - * Balance assertions will not see the effect of transactions in - previous files. (Usually this doesn't matter as each file will set - the corresponding opening balances.) - * Some directives will not affect previous or subsequent files. - - If needed, you can work around these by using a single parent file -which includes the others, or concatenating the files into one, eg: 'cat -a.journal b.journal | hledger -f- CMD'. - - -File: hledger.info, Node: Strict mode, Prev: Multiple files, Up: Input - -2.5 Strict mode -=============== - -hledger checks input files for valid data. By default, the most -important errors are detected, while still accepting easy journal files -without a lot of declarations: - - * Are the input files parseable, with valid syntax ? - * Are all transactions balanced ? - * Do all balance assertions pass ? - - With the '-s'/'--strict' flag, additional checks are performed: - - * Are all accounts posted to, declared with an 'account' directive ? - (Account error checking) - * Are all commodities declared with a 'commodity' directive ? - (Commodity error checking) - * Are all commodity conversions declared explicitly ? - - You can use the check command to run individual checks - the ones -listed above and some more. - - -File: hledger.info, Node: Commands, Next: Options, Prev: Input, Up: Top - -3 Commands -********** - -hledger provides various subcommands for getting things done. Most of -these commands do not change the journal file; they just read it and -output a report. A few commands assist with adding data and file -management. Some often-used commands are 'add', 'print', 'register', -'balancesheet' and 'incomestatement'. - - To show a summary of commands, run 'hledger' with no arguments. You -can see the same commands summary at the start of PART 4: COMMANDS -below. - - To use a particular command, run 'hledger CMD [CMDOPTS] [CMDARGS]', - - * CMD is the full command name, or its standard abbreviation shown in - the commands list, or any unambiguous prefix of the name. - - * CMDOPTS are command-specific options, if any. Command-specific - options must be written after the command name. Eg: 'hledger print - -x'. - - * CMDARGS are additional arguments to the command, if any. Most - hledger commands accept arguments representing a query, to limit - the data in some way. Eg: 'hledger reg assets:checking'. - - To list a command's options, arguments, and documentation in the -terminal, run 'hledger CMD -h'. Eg: 'hledger bal -h'. - -* Menu: - -* Add-on commands:: - - -File: hledger.info, Node: Add-on commands, Up: Commands - -3.1 Add-on commands -=================== - -In addition to the built-in commands, you can install _add-on commands_, -which will also appear in hledger's commands list. Some of these can be -installed as separate packages; others can be found in hledger's bin/ -directory, documented at https://hledger.org/scripts.html. - - 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 directly: 'hledger-ui --watch'. - - Or you can run them with hledger, like built-in commands: 'hledger ui ---watch'. In this case hledger's config file will be used, so you can -set custom options for the addon there. (Before hledger 1.50, an '--' -argument was needed before addon options, but not any more.) - - -File: hledger.info, Node: Options, Next: Output, Prev: Commands, Up: Top - -4 Options -********* - -Run 'hledger -h' to see general command line help. Options can be -written either before or after the command name. These options are -specific to the 'hledger' CLI: - -Flags: - --conf=CONFFILE Use extra options defined in this config file. If - not specified, searches upward and in XDG config - dir for hledger.conf (or .hledger.conf in $HOME). - -n --no-conf ignore any config file - - And the following general options are common to most hledger -commands: - -General input/data transformation flags: - -f --file=[FMT:]FILE Read data from FILE, or from stdin if FILE is -, - inferring format from extension or a FMT: prefix. - Can be specified more than once. If not specified, - reads from $LEDGER_FILE or $HOME/.hledger.journal. - --rules=RULESFILE Use rules defined in this rules file for - converting subsequent CSV/SSV/TSV files. If not - specified, uses FILE.csv.rules for each FILE.csv. - --alias=A=B|/RGX/=RPL transform account names from A to B, or by - replacing regular expression matches - --auto generate extra postings by applying auto posting - rules ("=") to all transactions - --forecast[=PERIOD] Generate extra transactions from periodic rules - ("~"), from after the latest ordinary transaction - until 6 months from now. Or, during the specified - PERIOD (the equals is required). Auto posting rules - will also be applied to these transactions. In - hledger-ui, also make future-dated transactions - visible at startup. - -I --ignore-assertions don't check balance assertions by default - --txn-balancing=... how to check that transactions are balanced: - 'old': use global display precision - 'exact': use transaction precision (default) - --infer-costs infer conversion equity postings from costs - --infer-equity infer costs from conversion equity postings - --infer-market-prices infer market prices from costs - --pivot=TAGNAME use a different field or tag as account names - -s --strict do extra error checks (and override -I) - --verbose-tags add tags indicating generated/modified data - -General output/reporting flags (supported by some commands): - -b --begin=DATE include postings/transactions on/after this date - -e --end=DATE include postings/transactions before this date - (with a report interval, will be adjusted to - following subperiod end) - -D --daily multiperiod report with 1 day interval - -W --weekly multiperiod report with 1 week interval - -M --monthly multiperiod report with 1 month interval - -Q --quarterly multiperiod report with 1 quarter interval - -Y --yearly multiperiod report with 1 year interval - -p --period=PERIODEXP set begin date, end date, and/or report interval, - with more flexibility - --today=DATE override today's date (affects relative dates) - --date2 match/use secondary dates instead (deprecated) - -U --unmarked include only unmarked postings/transactions - -P --pending include only pending postings/transactions - -C --cleared include only cleared postings/transactions - (-U/-P/-C can be combined) - -R --real include only non-virtual postings - -E --empty Show zero items, which are normally hidden. - In hledger-ui & hledger-web, do the opposite. - --depth=DEPTHEXP if a number (or -NUM): show only top NUM levels - of accounts. If REGEXP=NUM, only apply limiting to - accounts matching the regular expression. - -B --cost show amounts converted to their cost/sale amount - -V --market Show amounts converted to their value at period - end(s) in their default valuation commodity. - Equivalent to --value=end. - -X --exchange=COMM Show amounts converted to their value at period - end(s) in the specified commodity. - Equivalent to --value=end,COMM. - --value=WHEN[,COMM] show amounts converted to their value on the - specified date(s) in their default valuation - commodity or a specified commodity. WHEN can be: - 'then': value on transaction dates - 'end': value at period end(s) - 'now': value today - YYYY-MM-DD: value on given date - -c --commodity-style=S Override a commodity's display style. - Eg: -c '.' or -c '1.000,00 EUR' - --pretty[=YN] Use box-drawing characters in text output? Can be - 'y'/'yes' or 'n'/'no'. - If YN is specified, the equals is required. - -General help flags: - -h --help show command line help - --tldr show command examples with tldr - --info show the manual with info - --man show the manual with man - --version show version information - --debug=[1-9] show this much debug output (default: 1) - --pager=YN use a pager when needed ? y/yes (default) or n/no - --color=YNA --colour use ANSI color ? y/yes, n/no, or auto (default) - - Usually hledger accepts any unambiguous flag prefix, eg you can write -'--tl' instead of '--tldr' or '--dry' instead of '--dry-run'. - - You can combine short flags which don't take arguments, eg you can -write '-MAST' instead of '-M -A -S -T'. Flags requiring an argument -can't be combined in this way ('-If FILE' won't work). - - If the same option appears more than once in a command line, usually -the last (right-most) wins. Similarly, if mutually exclusive flags are -used together, the right-most wins. (When flags are mutually exclusive, -they'll usually have a group prefix in -help.) - - With most commands, arguments are interpreted as a hledger query -which filter the data. Some queries can be expressed either with -options or with arguments. - - Below are more tips for using the command line interface - feel free -to skip these until you need them. - -* Menu: - -* Special characters:: -* Unicode characters:: -* Regular expressions:: -* Argument files:: -* Config files:: -* Shell completions:: - - -File: hledger.info, Node: Special characters, Next: Unicode characters, Up: Options - -4.1 Special characters -====================== - -Here we touch on shell escaping/quoting rules, and give some examples. -This is a slightly complicated topic which you may not need at first, -but you should be aware of it, so you can return here when needed. - - If you are able to minimise the use of special characters in your -data, you won't need escaping as much, and your command lines will be -simpler. For example, avoiding spaces in account names, and using an -ISO-4217 currency code like 'USD' instead of the '$' currency symbol, -can be helpful. - - But if you want to use spaced account names and '$', go right ahead; -escaping isn't a big deal. - -* Menu: - -* Escaping shell special characters:: -* Escaping on Windows:: -* Escaping regular expression special characters:: -* Escaping add-on arguments:: -* Escaping in other situations:: -* Using a wild card:: - - -File: hledger.info, Node: Escaping shell special characters, Next: Escaping on Windows, Up: Special characters - -4.1.1 Escaping shell special characters ---------------------------------------- - -At the command line, characters which have special meaning for your -shell must be "shell-escaped" (AKA "quoted") if you want hledger to see -them. Often these include space, '<', '>', '(', ')', '|', '\', '$' -and/or '%'. - - For example, to match an account name containing the phrase "credit -card", don't write this: - -$ hledger register credit card - - In that command, "credit" and "card" are treated as separate query -arguments (described below), so this would match accounts containing -either word. Instead, enclose the phrase in double or single quotes: - -$ hledger register "credit card" - - In Unix shells, writing a backslash before the character can also -work. Eg: - -$ hledger register credit\ card - - Some shell characters still have a special meaning inside double -quotes, such as the dollar sign ('$'). Eg in '"assets:$account"', the -bash shell would replace '$account' with the value of a shell variable -with that name. When you don't want that, use single quotes, which -escape more strongly: - -$ hledger balance 'assets:$account' - - -File: hledger.info, Node: Escaping on Windows, Next: Escaping regular expression special characters, Prev: Escaping shell special characters, Up: Special characters - -4.1.2 Escaping on Windows -------------------------- - -If you are using hledger in a Powershell or Command window on Microsoft -Windows, the escaping rules are different: - - * In a Powershell window ('powershell', blue background), you must - use double quotes or single quotes (not backslash). - * In a Command window ('cmd', black background), you must use double - quotes (not single quotes or backslash). - - The next two sections were written for Unix-like shells, so might -need to be adapted if you're using 'cmd' or 'powershell'. (Edits -welcome.) - - -File: hledger.info, Node: Escaping regular expression special characters, Next: Escaping add-on arguments, Prev: Escaping on Windows, Up: Special characters - -4.1.3 Escaping regular expression special characters ----------------------------------------------------- - -Many hledger arguments are regular expressions (described below), and -these too have characters which cause special effects. Some of those -characters are '.', '^', '$', '[', ']', '(', ')', '|', and '\'. When -you don't want these to cause special effects, you can "regex-escape" -them by writing '\' (a backslash) before them. But since backslash is -also special to the shell, you may need to also shell-escape the -backslashes. - - Eg, in the bash shell, to match a literal '$' sign, you could write: - -$ hledger balance cur:\\$ - - or: - -$ hledger balance 'cur:\$' - - (The dollar sign is regex-escaped by the backslash preceding it. -Then that backslash is shell-escaped by another backslash, or by single -quotes.) - - -File: hledger.info, Node: Escaping add-on arguments, Next: Escaping in other situations, Prev: Escaping regular expression special characters, Up: Special characters - -4.1.4 Escaping add-on arguments -------------------------------- - -When you run an external add-on command with 'hledger' (described -below), any options or arguments being passed through to the add-on -executable lose one level of shell-escaping, so you must add an extra -level of shell-escaping to compensate. - - Eg, in the bash shell, to run the 'ui' add-on and match a literal '$' -sign, you need to write: - -$ hledger ui cur:'\\$' - - or: - -$ hledger ui cur:\\\\$ - - If you are wondering why _four_ backslashes: - - * '$' is unescaped - * '\$' is regex-escaped - * '\\$' is regex-escaped, then shell-escaped - * '\\\\$' is regex-escaped, then shell-escaped, then both slashes are - shell-escaped once more for hledger argument pass-through. - - Or you can avoid such triple-escaping, by running the add-on -executable directly: - -$ hledger-ui cur:\\$ - - -File: hledger.info, Node: Escaping in other situations, Next: Using a wild card, Prev: Escaping add-on arguments, Up: Special characters - -4.1.5 Escaping in other situations ----------------------------------- - -hledger options and arguments are sometimes used in places other than -the command line, with different escaping rules. For example, -backslash-quoting generally does not work there. Here are some more -tips. - -In Windows 'cmd' Use double quotes -In Windows Use single or double quotes -'powershell' -In hledger-ui's Use single or double quotes -filter prompt -In hledger-web's Use single or double quotes -search form -In an argument Don't use spaces, don't shell-escape, do -file regex-escape when needed -In a config file Use single or double quotes, and enclose the whole - argument ('"desc:a b"' not 'desc:"a b"') -In 'ghci' (the Use double quotes, and enclose the whole argument -Haskell REPL) - - -File: hledger.info, Node: Using a wild card, Prev: Escaping in other situations, Up: Special characters - -4.1.6 Using a wild card ------------------------ - -When escaping a special character is too much hassle (or impossible), -you can often just write '.' (period) instead. In regular expressions, -this means "accept any character here". Eg: - -$ hledger register credit.card - - -File: hledger.info, Node: Unicode characters, Next: Regular expressions, Prev: Special characters, Up: Options - -4.2 Unicode characters -====================== - -hledger is expected to handle non-ascii characters correctly: - - * they should be parsed correctly in input files and on the command - line, by all hledger tools (add, iadd, hledger-web's - search/add/edit forms, etc.) - - * they should be displayed correctly by all hledger tools, and - on-screen alignment should be preserved. - - This requires a well-configured environment. Here are some tips: - - * A system locale must be configured, which can decode the characters - being used. This is essential - see Text encoding and Install: - Text encoding. - - * Your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) - must support unicode. On Windows, you may need to use Windows - Terminal. - - * The terminal must be using a font which includes the required - unicode glyphs. - - * The terminal should be configured to display wide characters as - double width (for report alignment). - - * On Windows, for best results you should run hledger in the same - kind of environment in which it was built. Eg hledger built in the - standard CMD.EXE environment (like the binaries on our download - page) might show display problems when run in a cygwin or msys - terminal, and vice versa. (See eg #961). - - -File: hledger.info, Node: Regular expressions, Next: Argument files, Prev: Unicode characters, Up: Options - -4.3 Regular expressions -======================= - -A regular expression (regexp) is a small piece of text where certain -characters (like '.', '^', '$', '+', '*', '()', '|', '[]', '\') have -special meanings, forming a tiny language for matching text precisely - -very useful in hledger and elsewhere. To learn all about them, visit -regular-expressions.info. - - hledger supports regexps whenever you are entering a pattern to match -something, eg in query arguments, account aliases, CSV if rules, -hledger-web's search form, hledger-ui's '/' search, etc. You may need -to wrap them in quotes, especially at the command line (see Special -characters above). Here are some examples: - - Account name queries (quoted for command line use): - -Regular expression: Matches: -------------------- ------------------------------------------------------------ -bank assets:bank, assets:bank:savings, expenses:art:banksy, ... -:bank assets:bank:savings, expenses:art:banksy -:bank: assets:bank:savings -'^bank' none of those ( ^ matches beginning of text ) -'bank$' assets:bank ( $ matches end of text ) -'big \$ bank' big $ bank ( \ disables following character's special meaning ) -'\bbank\b' assets:bank, assets:bank:savings ( \b matches word boundaries ) -'(sav|check)ing' saving or checking ( (|) matches either alternative ) -'saving|checking' saving or checking ( outer parentheses are not needed ) -'savings?' saving or savings ( ? matches 0 or 1 of the preceding thing ) -'my +bank' my bank, my bank, ... ( + matches 1 or more of the preceding thing ) -'my *bank' mybank, my bank, my bank, ... ( * matches 0 or more of the preceding thing ) -'b.nk' bank, bonk, b nk, ... ( . matches any character ) - - Some other queries: - -desc:'amazon|amzn|audible' Amazon transactions -cur:EUR amounts with commodity symbol containing EUR -cur:'\$' amounts with commodity symbol containing $ -cur:'^\$$' only $ amounts, not eg AU$ or CA$ -cur:....? amounts with 4-or-more-character symbols -tag:.=202[1-3] things with any tag whose value contains 2021, 2022 or 2023 - - Account name aliases: accept '.' instead of ':' as account separator: - -alias /\./=: replaces all periods in account names with colons - - Show multiple top-level accounts combined as one: - ---alias='/^[^:]+/=combined' ( [^:] matches any character other than : ) - - Show accounts with the second-level part removed: - ---alias '/^([^:]+):[^:]+/ = \1' - match a top-level account and a second-level account - and replace those with just the top-level account - ( \1 in the replacement text means "whatever was matched - by the first parenthesised part of the regexp" - - CSV rules: match CSV records containing dining-related MCC codes: - -if \?MCC581[124] - - Match CSV records with a specific amount around the end/start of -month: - -if %amount \b3\.99 -& %date (29|30|31|01|02|03)$ - -* Menu: - -* hledger's regular expressions:: - - -File: hledger.info, Node: hledger's regular expressions, Up: Regular expressions - -4.3.1 hledger's regular expressions ------------------------------------ - -hledger's regular expressions come from the regex-tdfa library. If -they're not doing what you expect, it's important to know exactly what -they support: - - 1. they are case insensitive - 2. they are infix matching (they do not need to match the entire thing - being matched) - 3. they are POSIX ERE (extended regular expressions) - 4. they also support GNU word boundaries ('\b', '\B', '\<', '\>') - 5. backreferences are supported when doing text replacement in account - aliases or CSV rules, where backreferences can be used in the - replacement string to reference capturing groups in the search - regexp. Otherwise, if you write '\1', it will match the digit '1'. - 6. they do not support mode modifiers ('(?s)'), character classes - ('\w', '\d'), or anything else not mentioned above. - 7. they may not (I'm guessing not) properly support right-to-left or - bidirectional text. - - Some things to note: - - * In the 'alias' directive and '--alias' option, regular expressions - must be enclosed in forward slashes ('/REGEX/'). Elsewhere in - hledger, these are not required. - - * In queries, to match a regular expression metacharacter like '$' as - a literal character, prepend a backslash. Eg to search for amounts - with the dollar sign in hledger-web, write 'cur:\$'. - - * On the command line, some metacharacters like '$' have a special - meaning to the shell and so must be escaped at least once more. - See Special characters. - - -File: hledger.info, Node: Argument files, Next: Config files, Prev: Regular expressions, Up: Options - -4.4 Argument files -================== - -You can save a set of command line options and arguments in a file, and -then reuse them by writing '@FILENAME' as a command line argument. Eg: -'hledger bal @foo.args'. - - An argument file's format is more restrictive than the command line. -Each line should contain just one option or argument. Don't use spaces -except inside quotes; write '=' or nothing between a flag and its -argument. If you use quotes, they must enclose the whole line. For the -special characters mentioned above, use one less level of quoting than -you would at the command line. - - -File: hledger.info, Node: Config files, Next: Shell completions, Prev: Argument files, Up: Options - -4.5 Config files -================ - -With hledger 1.40+, you can save extra command line options and -arguments in a more featureful hledger config file. Here's a small -example: - -# General options are listed first, and used with hledger commands that support them. ---pretty - -# Options following a `[COMMAND]` heading are used with that hledger command only. -[print] ---explicit --infer-costs - - To use a config file, specify it with the '--conf' option. Its -options will be inserted near the start of your command line, so you can -override them with command line options if needed. - - Or, you can set up an automatic config file that is used whenever you -run hledger, by creating 'hledger.conf' in the current directory or -above, or '.hledger.conf' in your home directory ('~/.hledger.conf'), or -'hledger.conf' in your XDG config directory -('~/.config/hledger/hledger.conf'). - - Here is another example config you could start with: -https://github.com/simonmichael/hledger/blob/master/hledger.conf.sample - - You can put not only options, but also arguments in a config file. -If the first word in a config file's top (general) section does not -begin with a dash (eg: 'print'), it is treated as the command argument -(overriding any argument on the command line). - - On unix machines, you can add a shebang line at the top of a config -file, set executable permission on the file, and use it like a script. -Eg (the '-S' is needed on some operating systems): - -#!/usr/bin/env -S hledger --conf - - You can ignore config files by adding the '-n'/'--no-conf' flag to -the command line. This is useful when using hledger in scripts, or when -troubleshooting. When both '--conf' and '--no-conf' options are used, -the right-most wins. - - To inspect the processing of config files, use '--debug' or -'--debug=8'. Or, run the 'setup' command, which will display any active -config files. ('setup' is not affected by config files itself, unlike -other commands.) - - *Warning!* - - There aren't many hledger features that need a warning, but this is -one! - - Automatic config files, while convenient, also make hledger less -predictable and dependable. It's easy to make a config file that -changes a report's behaviour, or breaks your hledger-using -scripts/applications, in ways that will surprise you later. - - If you don't want this, - - 1. Just don't create a hledger.conf file on your machine. - 2. Also be alert to downloaded directories which may contain a - hledger.conf file. - 3. Also if you are sharing scripts or examples or support, consider - that others may have a hledger.conf file. - - Conversely, once you decide to use this feature, try to remember: - - 1. Whenever a hledger command does not work as expected, try it again - with '-n' ('--no-conf') to see if a config file was to blame. - 2. Whenever you call hledger from a script, consider whether that call - should use '-n' or not. - 3. Be conservative about what you put in your config file; try to - consider the effect on all your reports. - 4. To troubleshoot the effect of config files, run with '--debug' or - '--debug 8'. - - The config file feature was added in hledger 1.40. - - -File: hledger.info, Node: Shell completions, Prev: Config files, Up: Options - -4.6 Shell completions -===================== - -If you use the bash or zsh shells, you can optionally set up -context-sensitive autocompletion for hledger command lines. Try -pressing 'hledger' (should list all hledger commands) -or 'hledger reg acct:' (should list your top-level account -names). If completions aren't working, or for more details, see Install -> Shell completions. - - -File: hledger.info, Node: Output, Next: Environment, Prev: Options, Up: Top - -5 Output -******** - -* Menu: - -* Output destination:: -* Output format:: -* Commodity styles:: -* Debug output:: - - -File: hledger.info, Node: Output destination, Next: Output format, Up: Output - -5.1 Output destination -====================== - -hledger commands send their output to the terminal by default. You can -of course redirect this, eg into a file, using standard shell syntax: - -$ hledger print > foo.txt - - Some commands (print, register, stats, the balance commands) also -provide the '-o'/'--output-file' option, which does the same thing -without needing the shell. Eg: - -$ hledger print -o foo.txt -$ hledger print -o - # write to stdout (the default) - - -File: hledger.info, Node: Output format, Next: Commodity styles, Prev: Output destination, Up: Output - -5.2 Output format -================= - -Some commands offer other kinds of output, not just text on the -terminal. Here are those commands and the formats currently supported: - -command txt html csv/tsv fods beancount sql json ------------------------------------------------------------------------------- -aregister Y Y Y Y Y -balance Y Y Y Y Y -balancesheet Y Y Y Y Y -balancesheetequity Y Y Y Y Y -cashflow Y Y Y Y Y -incomestatement Y Y Y Y Y -print Y Y Y Y Y Y Y -register Y Y Y Y Y - - You can also see which output formats a command supports by running -'hledger CMD -h' and looking for the '-O'/'--output-format=FMT' option, - - You can select the output format by using that option: - -$ hledger print -O csv # print CSV to standard output - - or by choosing a suitable filename extension with the -'-o'/'--output-file=FILE.FMT' option: - -$ hledger balancesheet -o foo.csv # write CSV to foo.csv - - The '-O' option can be combined with '-o' to override the file -extension if needed: - -$ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt - - Here are some notes about the various output formats. - -* Menu: - -* Text output:: -* HTML output:: -* CSV / TSV output:: -* FODS output:: -* Beancount output:: -* SQL output:: -* JSON output:: - - -File: hledger.info, Node: Text output, Next: HTML output, Up: Output format - -5.2.1 Text output ------------------ - -This is the default: human readable, plain text report output, suitable -for viewing with a monospace font in a terminal. If your data contains -unicode or wide characters, you'll need a terminal and font that render -those correctly. (This can be challenging on MS Windows.) - - Some reports ('register', 'aregister') will normally use the full -window width. If this isn't working or you want to override it, you can -use the '-w'/'--width' option. - - Balance reports ('balance', 'balancesheet', 'incomestatement'...) -use whatever width they need. Multi-period multi-currency reports can -often be wider than the window. Besides using a pager, helpful -techniques for this situation include '--layout=bare', '-V', 'cur:', -'--transpose', '--tree', '--depth', '--drop', switching to html output, -etc. - -* Menu: - -* Box-drawing characters:: -* Colour:: -* Paging:: - - -File: hledger.info, Node: Box-drawing characters, Next: Colour, Up: Text output - -5.2.1.1 Box-drawing characters -.............................. - -hledger draws simple table borders by default, to minimise the risk of -display problems caused by a terminal/font not supporting box-drawing -characters. - - But your terminal and font probably do support them, so we recommend -using the '--pretty' flag to show prettier tables in the terminal. This -is a good flag to add to your hledger config file. - - -File: hledger.info, Node: Colour, Next: Paging, Prev: Box-drawing characters, Up: Text output - -5.2.1.2 Colour -.............. - -hledger tries to automatically detect ANSI colour and text styling -support and use it when appropriate. (Currently, it is used rather -minimally: some reports show negative numbers in red, and help output -uses bold text for emphasis.) - - You can override this by setting the 'NO_COLOR' environment variable -to disable it, or by using the '--color/--colour' option, perhaps in -your config file, with a 'y'/'yes' or 'n'/'no' value to force it on or -off. - - -File: hledger.info, Node: Paging, Prev: Colour, Up: Text output - -5.2.1.3 Paging -.............. - -In unix-like environments, when displaying large output (in any output -format) in the terminal, hledger tries to use a pager when appropriate. -(You can disable this with the '--pager=no' option, perhaps in your -config file.) - - The pager shows one page of text at a time, and lets you scroll -around to see more. While it is active, usually 'SPACE' shows the next -page, 'h' shows help, and 'q' quits. The home/end/page up/page -down/cursor keys, and mouse scrolling, may also work. - - hledger will use the pager specified by the 'PAGER' environment -variable, otherwise 'less' if available, otherwise 'more' if available. -(With one exception: 'hledger help -p TOPIC' will always use 'less', so -that it can scroll to the topic.) - - The pager is expected to display hledger's ANSI colour and text -styling. If you see junk characters, you might need to configure your -pager to handle ANSI codes. Or you could disable colour as described -above. - - If you are using the 'less' pager, hledger automatically appends a -number of options to the 'LESS' variable to enable ANSI colour and a -number of other conveniences. (At the time of writing: -chop-long-lines --hilite-unread -ignore-case -no-init -quit-at-eof -quit-if-one-screen --RAW-CONTROL-CHARS -shift=8 -squeeze-blank-lines -use-backslash ). If -these don't work well, you can set your preferred options in the -'HLEDGER_LESS' variable, which will be used instead. - - -File: hledger.info, Node: HTML output, Next: CSV / TSV output, Prev: Text output, Up: Output format - -5.2.2 HTML output ------------------ - -HTML output can be styled by an optional 'hledger.css' file in the same -directory. - - HTML output will be a HTML fragment, not a complete HTML document. -Like other hledger output, for non-ascii characters it will use the -system locale's text encoding (see Text encoding). - - -File: hledger.info, Node: CSV / TSV output, Next: FODS output, Prev: HTML output, Up: Output format - -5.2.3 CSV / TSV output ----------------------- - -In CSV or TSV output, digit group marks (such as thousands separators) -are disabled automatically. - - -File: hledger.info, Node: FODS output, Next: Beancount output, Prev: CSV / TSV output, Up: Output format - -5.2.4 FODS output ------------------ - -FODS is the OpenDocument Spreadsheet format as plain XML, as accepted by -LibreOffice and OpenOffice. If you use their spreadsheet applications, -this is better than CSV because it works across locales (decimal point -vs. decimal comma, character encoding stored in XML header, thus no -problems with umlauts), it supports fixed header rows and columns, cell -types (string vs. number vs. date), separation of number and currency -(currency is displayed but the cell type is still a number accessible -for computation), styles (bold), borders. Btw. you can still extract -CSV from FODS/ODS using various utilities like 'libreoffice --headless' -or ods2csv. - - -File: hledger.info, Node: Beancount output, Next: SQL output, Prev: FODS output, Up: Output format - -5.2.5 Beancount output ----------------------- - -This is Beancount's journal format. You can use this to export your -hledger data to Beancount, eg to use the Fava web app. - - hledger will try to adjust your data to suit Beancount, -automatically. Be cautious and check the conversion until you are -confident it is good. If you plan to export to Beancount often, you may -want to follow its conventions, for a cleaner conversion: - - * use Beancount-friendly account names - * use currency codes instead of currency symbols - * use cost notation instead of equity conversion postings - * avoid virtual postings, balance assignments, and secondary dates. - - There is one big adjustment you must handle yourself: for Beancount, -the top level account names must be 'Assets', 'Liabilities', 'Equity', -'Income', and/or 'Expenses'. You can use account aliases to rewrite -your account names temporarily, if needed, as in this -hledger2beancount.conf config file. - - 2024-12-20: Some more things not yet handled for you: - - * P directives are not converted automatically - convert those - yourself. - * Balance assignments are not converted (Beancount doesn't support - them) - replace those with explicit amounts. - -* Menu: - -* Beancount account names:: -* Beancount commodity names:: -* Beancount virtual postings:: -* Beancount metadata:: -* Beancount costs:: -* Beancount operating currency:: - - -File: hledger.info, Node: Beancount account names, Next: Beancount commodity names, Up: Beancount output - -5.2.5.1 Beancount account names -............................... - -Aside from the top-level names, hledger will adjust your account names -to make valid Beancount account names, by capitalising each part, -replacing spaces with '-', replacing other unsupported characters with -'C', prepending 'A' to account name parts which don't begin -with a letter or digit, and appending ':A' to account names which have -only one part. - - -File: hledger.info, Node: Beancount commodity names, Next: Beancount virtual postings, Prev: Beancount account names, Up: Beancount output - -5.2.5.2 Beancount commodity names -................................. - -hledger will adjust your commodity names to make valid Beancount -commodity/currency names, which must be 2-24 uppercase letters, digits, -or ''', '.', '_', '-', beginning with a letter and ending with a letter -or digit. hledger will convert known currency symbols to ISO 4217 -currency codes, capitalise letters, replace spaces with '-', replace -other unsupported characters with 'C', and prepend or append -'C' if needed. - - -File: hledger.info, Node: Beancount virtual postings, Next: Beancount metadata, Prev: Beancount commodity names, Up: Beancount output - -5.2.5.3 Beancount virtual postings -.................................. - -Beancount doesn't allow virtual postings; if you have any, they will be -omitted from beancount output. - - -File: hledger.info, Node: Beancount metadata, Next: Beancount costs, Prev: Beancount virtual postings, Up: Beancount output - -5.2.5.4 Beancount metadata -.......................... - -hledger tags will be converted to Beancount metadata (except for tags -whose name begins with '_'). Metadata names will be adjusted to be -Beancount-compatible: beginning with a lowercase letter, at least two -characters long, and with unsupported characters encoded. Metadata -values will use Beancount's string type. - - In hledger, objects can have the same tag repeated with multiple -values. Eg an 'assets:cash' account might have both 'type:Asset' and -'type:Cash' tags. For Beancount these will be combined into one, with -the values combined, comma separated. Eg: 'type: "Asset, Cash"'. - - -File: hledger.info, Node: Beancount costs, Next: Beancount operating currency, Prev: Beancount metadata, Up: Beancount output - -5.2.5.5 Beancount costs -....................... - -Beancount doesn't allow redundant costs and conversion postings as -hledger does. If you have any of these, the conversion postings will be -omitted. Currently we support at most one cost + conversion postings -group per transaction. - - -File: hledger.info, Node: Beancount operating currency, Prev: Beancount costs, Up: Beancount output - -5.2.5.6 Beancount operating currency -.................................... - -Declaring an operating currency (or several) improves Beancount and Fava -reports. Currently hledger will declare each currency used in cost -amounts as an operating currency. If needed, replace these with your -own declaration, like - -option "operating_currency" "USD" - - -File: hledger.info, Node: SQL output, Next: JSON output, Prev: Beancount output, Up: Output format - -5.2.6 SQL output ----------------- - -SQL output is expected to work at least with SQLite, MySQL and Postgres. - - The SQL statements are expected to be executed in the empty database. -If you already have tables created via SQL output of hledger, you would -probably want to either clear data from these (via 'delete' or -'truncate' SQL statements) or 'drop' the tables completely before -import; otherwise your postings would be duplicated. - - For SQLite, it is more useful if you modify the generated 'id' field -to be a PRIMARY KEY. Eg: - -$ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ... - - This is not yet much used; feedback is welcome. - - -File: hledger.info, Node: JSON output, Prev: SQL output, Up: Output format - -5.2.7 JSON output ------------------ - -Our JSON is rather large and verbose, since it is a faithful -representation of hledger's internal data types. To understand its -structure, read the Haskell type definitions, which are mostly in -https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs. -hledger-web's OpenAPI specification may also be relevant. - - hledger stores numbers with sometimes up to 255 significant digits. -This is too many digits for most JSON consumers, so in JSON output we -round numbers to at most 10 decimal places. (We don't limit the number -of integer digits.) If you find this causing problems, please let us -know. Related: #1195 - - This is not yet much used; feedback is welcome. - - -File: hledger.info, Node: Commodity styles, Next: Debug output, Prev: Output format, Up: Output - -5.3 Commodity styles -==================== - -When displaying amounts, hledger infers a standard display style for -each commodity/currency, as described below in Commodity display style. - - If needed, this can be overridden by a '-c/--commodity-style' option -(except for cost amounts and amounts displayed by the 'print' command, -which are always displayed with all decimal digits). For example, the -following will force dollar amounts to be displayed as shown: - -$ hledger print -c '$1.000,0' - - This option can be repeated to set the display style for multiple -commodities/currencies. Its argument is as described in the commodity -directive. - - In some cases hledger will adjust number formatting to improve their -parseability (such as adding trailing decimal marks when needed). - - -File: hledger.info, Node: Debug output, Prev: Commodity styles, Up: Output - -5.4 Debug output -================ - -We intend hledger to be relatively easy to troubleshoot, introspect and -develop. You can add '--debug[=N]' to any hledger command line to see -additional debug output. N ranges from 1 (least output, the default) to -9 (maximum output). Typically you would start with 1 and increase until -you are seeing enough. Debug output goes to stderr, and is not affected -by '-o/--output-file' (unless you redirect stderr to stdout, eg: -'2>&1'). It will be interleaved with normal output, which can help -reveal when parts of the code are evaluated. To capture debug output in -a log file instead, you can usually redirect stderr, eg: - -hledger bal --debug=3 2>hledger.log - - (This option doesn't work in a config file yet.) - - -File: hledger.info, Node: Environment, Next: PART 2 DATA FORMATS, Prev: Output, Up: Top - -6 Environment -************* - -These environment variables affect hledger: - - *HLEDGER_LESS* If 'less' is your pager, this variable specifies the -'less' options hledger should use. (Otherwise, 'LESS' + custom options -are used.) - - *LEDGER_FILE* The main journal file to use when not specified with -'-f/--file'. Default: '$HOME/.hledger.journal'. - - *NO_COLOR* If this environment variable exists (with any value, -including empty), hledger will not use ANSI color codes in terminal -output, unless overridden by an explicit '--color=y' or '--colour=y' -option. - - -File: hledger.info, Node: PART 2 DATA FORMATS, Next: Journal, Prev: Environment, Up: Top - -7 PART 2: DATA FORMATS -********************** - - -File: hledger.info, Node: Journal, Next: CSV, Prev: PART 2 DATA FORMATS, Up: Top - -8 Journal -********* - -hledger's usual data source is a plain text file containing journal -entries in hledger 'journal' format. If you're looking for a quick -reference, jump ahead to the journal cheatsheet (or use the table of -contents at https://hledger.org/hledger.html). - - This file represents an accounting General Journal. The '.journal' -file extension is most often used, though not strictly required. The -journal file contains a number of transaction entries, each describing a -transfer of money (or any commodity) between two or more named accounts, -in a simple format readable by both hledger and humans. - - hledger's journal format is compatible with most of Ledger's journal -format, but not all of it. The differences and interoperation tips are -described at hledger and Ledger. With some care, and by avoiding -incompatible features, you can keep your hledger journal readable by -Ledger and vice versa. This can useful eg for comparing the behaviour -of one app against the other. - - You can use hledger without learning any more about this file; just -use the add or web or import commands to create and update it. - - Many users, though, edit the journal file with a text editor, and -track changes with a version control system such as git. Editor add-ons -such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and -hledger-vscode for Visual Studio Code, make this easier, adding colour, -formatting, tab completion, and useful commands. See Editor -configuration at hledger.org for the full list. - - A hledger journal file can contain three kinds of thing: comment -lines, transactions, and/or directives (including periodic transaction -rules and auto posting rules). Understanding the journal file format -will also give you a good understanding of hledger's data model. Here's -a quick cheatsheet/overview, followed by detailed descriptions of each -part. - -* Menu: - -* Journal cheatsheet:: -* Comments:: -* Transactions:: -* Dates:: -* Status:: -* Code:: -* Description:: -* Transaction comments:: -* Postings:: -* Account names:: -* Amounts:: -* Balance assertions:: -* Posting comments:: -* Transaction balancing:: -* Tags:: -* Directives:: -* account directive:: -* alias directive:: -* commodity directive:: -* decimal-mark directive:: -* include directive:: -* P directive:: -* payee directive:: -* tag directive:: -* Periodic transactions:: -* Auto postings:: -* Other syntax:: - - -File: hledger.info, Node: Journal cheatsheet, Next: Comments, Up: Journal - -8.1 Journal cheatsheet -====================== - -# Here is the main syntax of hledger's journal format -# (omitting extra Ledger compatibility syntax). - -############################################################################### - -# 1. These are comment lines, for notes or temporarily disabling things. -; They begin with # or ; - -comment -Or, lines can be enclosed within "comment" / "end comment". -This is a block of -commented lines. -end comment - -# Some journal entries can have semicolon comments at end of line ; like this -# Some of them require 2 or more spaces before the semicolon. - -############################################################################### - -# 2. Directives customise processing or output in some way. -# You don't need any directives to get started. -# But they can add more error checking, or change how things are displayed. -# They begin with a word, letter, or symbol. -# They are most often placed at the top, before transactions. - -account assets ; Declare valid account names and display order. -account assets:savings ; A subaccount. This one represents a bank account. -account assets:checking ; Another. Note, 2+ spaces after the account name. -account assets:receivable ; Accounting type is inferred from english names, -account passifs ; or declared with a "type" tag, type:L -account expenses ; type:X - ; A follow-on comment line, indented. -account expenses:rent ; Expense and revenue categories are also accounts. - ; Subaccounts inherit their parent's type. - -commodity $0.00 ; Declare valid commodities and their display styles. -commodity 1.000,00 EUR - -decimal-mark . ; The decimal mark used in this file (if ambiguous). - -payee Whole Foods ; Declare a valid payee name. - -tag trip ; Declare a valid tag name. - -P 2024-03-01 AAPL $179 ; Declare a market price for AAPL in $ on this date. - -include other.journal ; Include another journal file here. - -# Declare a recurring "periodic transaction", for budget/forecast reports -~ monthly set budget goals ; <- Note, 2+ spaces before the description. - (expenses:rent) $1000 - (expenses:food) $500 - -# Declare an auto posting rule, to modify existing transactions in reports -= revenues:consulting - liabilities:tax:2024:us *0.25 ; Add a tax liability & expense - expenses:tax:2024:us *-0.25 ; for 25% of the revenue. - -############################################################################### - -# 3. Transactions are what it's all about. -# They are dated events, usually movements of money between 2 or more accounts. -# They begin with a numeric date. -# Here is their basic shape: -# -# DATE DESCRIPTION ; The transaction's date and optional description. -# ACCOUNT1 AMOUNT ; A posting of an amount to/from this account, indented. -# ACCOUNT2 AMOUNT ; A second posting, balancing the first. -# ... ; More if needed. Amounts must sum to zero. -# ; Note, 2+ spaces between account names and amounts. - -2024-01-01 opening balances ; At the start, declare pre-existing balances this way. - assets:savings $10000 ; Account names can be anything. lower case is easy to type. - assets:checking $1000 ; assets, liabilities, equity, revenues, expenses are common. - liabilities:credit card $-500 ; liabilities, equity, revenues balances are usually negative. - equity:start ; One amount can be left blank. $-10500 is inferred here. - ; Some of these accounts we didn't declare above, - ; so -s/--strict would complain. - -2024-01-03 ! (12345) pay rent - ; Additional transaction comment lines, indented. - ; There can be a ! or * after the date meaning "pending" or "cleared". - ; There can be a parenthesised (code) after the date/status. - ; Amounts' sign shows direction of flow. - assets:checking $-500 ; Minus means removed from this account (credit). - expenses:rent $500 ; Plus means added to this account (debit). - -; Keeping transactions in date order is optional (but helps error checking). - -2024-01-02 Gringott's Bank | withdrawal ; Description can be PAYEE | NOTE - assets:bank:gold -10 gold - assets:pouch 10 gold - -2024-01-02 shopping - expenses:clothing 1 gold - expenses:wands 5 gold - assets:pouch -6 gold - -2024-01-02 receive gift - revenues:gifts -3 "Chocolate Frogs" ; Complex commodity symbols - assets:pouch 3 "Chocolate Frogs" ; must be in double quotes. - -2024-01-15 buy some shares, in two lots ; Cost can be noted. - assets:investments:2024-01-15 2.0 AAAA @ $1.50 ; @ means per-unit cost - assets:investments:2024-01-15-02 3.0 AAAA @@ $4 ; @@ means total cost - ; ^ Per-lot subaccounts are sometimes useful. - assets:checking $-7 - -2024-01-15 assert some account balances on this date - ; Balances can be asserted in any transaction, with =, for extra error checking. - ; Assertion txns like this one can be made with hledger close --assert --show-costs - ; - assets:savings $0 = $10000 - assets:checking $0 = $493 - assets:bank:gold 0 gold = -10 gold - assets:pouch 0 gold = 4 gold - assets:pouch 0 "Chocolate Frogs" = 3 "Chocolate Frogs" - assets:investments:2024-01-15 0.0 AAAA = 2.0 AAAA @ $1.50 - assets:investments:2024-01-15-02 0.0 AAAA = 3.0 AAAA @@ $4 - liabilities:credit card $0 = $-500 - -2024-02-01 note some event, or a transaction not yet fully entered, on this date - ; Postings are not required. - -# Consistent YYYY-MM-DD date format is recommended, -# but you can use . or / and omit leading zeros if you prefer. -2024.01.01 -2024/1/1 - - -File: hledger.info, Node: Comments, Next: Transactions, Prev: Journal cheatsheet, Up: Journal - -8.2 Comments -============ - -Lines in the journal will be ignored if they begin with a hash ('#') or -a semicolon (';'). (See also Other syntax.) hledger will also ignore -regions beginning with a 'comment' line and ending with an 'end comment' -line (or file end). Here's a suggestion for choosing between them: - - * '#' for top-level notes - * ';' for commenting out things temporarily - * 'comment' for quickly commenting large regions (remember it's - there, or you might get confused) - - Eg: - -# a comment line -; another commentline -comment -A multi-line comment block, -continuing until "end comment" directive -or the end of the current file. -end comment - - Some hledger entries can have same-line comments attached to them, -from ; (semicolon) to end of line. See Transaction comments, Posting -comments, and Account comments below. - - -File: hledger.info, Node: Transactions, Next: Dates, Prev: Comments, Up: Journal - -8.3 Transactions -================ - -Transactions are the main unit of information in a journal file. They -represent events, typically a movement of some quantity of commodities -between two or more named accounts. - - Each transaction is recorded as a journal entry, beginning with a -simple date in column 0. This can be followed by any of the following -optional fields, separated by spaces: - - * a status character (empty, '!', or '*') - * a code (any short number or text, enclosed in parentheses) - * a description (any remaining text until end of line or a semicolon) - * a comment (any remaining text following a semicolon until end of - line, and any following indented lines beginning with a semicolon) - * 0 or more indented _posting_ lines, describing what was transferred - and the accounts involved (indented comment lines are also allowed, - but not blank lines or non-indented lines). - - Here's a simple journal file containing one transaction: - -2008/01/01 income - assets:bank:checking $1 - income:salary $-1 - - -File: hledger.info, Node: Dates, Next: Status, Prev: Transactions, Up: Journal - -8.4 Dates -========= - -* Menu: - -* Simple dates:: -* Posting dates:: - - -File: hledger.info, Node: Simple dates, Next: Posting dates, Up: Dates - -8.4.1 Simple dates ------------------- - -Dates in the journal file use _simple dates_ format: 'YYYY-MM-DD' or -'YYYY/MM/DD' or 'YYYY.MM.DD', with leading zeros optional. The year may -be omitted, in which case it will be inferred from the context: the -current transaction, the default year set with a 'Y' directive, or the -current date when the command is run. Some examples: '2010-01-31', -'2010/01/31', '2010.1.31', '1/31'. - - (The UI also accepts simple dates, as well as the more flexible smart -dates documented in the hledger manual.) - - -File: hledger.info, Node: Posting dates, Prev: Simple dates, Up: Dates - -8.4.2 Posting dates -------------------- - -You can give individual postings a different date from their parent -transaction, by adding a posting comment containing a tag (see below) -like 'date:DATE'. This is probably the best way to control posting -dates precisely. Eg in this example the expense should appear in May -reports, and the deduction from checking should be reported on 6/1 for -easy bank reconciliation: - -2015/5/30 - expenses:food $10 ; food purchased on saturday 5/30 - assets:checking ; bank cleared it on monday, date:6/1 - -$ hledger -f t.j register food -2015-05-30 expenses:food $10 $10 - -$ hledger -f t.j register checking -2015-06-01 assets:checking $-10 $-10 - - DATE should be a simple date; if the year is not specified it will -use the year of the transaction's date. -The 'date:' tag must have a valid simple date value if it is present, eg -a 'date:' tag with no value is not allowed. - - -File: hledger.info, Node: Status, Next: Code, Prev: Dates, Up: Journal - -8.5 Status -========== - -Transactions (or individual postings within a transaction) can have a -status mark, which is a single character before the transaction -description (or posting account name), separated from it by a space, -indicating one of three statuses: - -mark status - ------------------ - unmarked -'!' pending -'*' cleared - - When reporting, you can filter by status with the '-U/--unmarked', -'-P/--pending', and '-C/--cleared' flags (and you can combine these, eg -'-UP' to match all except cleared things). Or you can use the -'status:', 'status:!', and 'status:*' queries, or the U, P, C keys in -hledger-ui. - - (Note: in Ledger the "unmarked" state is called "uncleared"; in -hledger we renamed it to "unmarked" for semantic clarity.) - - Status marks are optional, but can be helpful eg for reconciling with -real-world accounts. Some editor modes provide highlighting and -shortcuts for working with status. Eg in Emacs ledger-mode, you can -toggle transaction status with C-c C-e, or posting status with C-c C-c. - - What "uncleared", "pending", and "cleared" actually mean is up to -you. Here's one suggestion: - -status meaning --------------------------------------------------------------------------- -uncleared recorded but not yet reconciled; needs review -pending tentatively reconciled (if needed, eg during a big - reconciliation) -cleared complete, reconciled as far as possible, and considered - correct - - With this scheme, you would use '-PC' to see the current balance at -your bank, '-U' to see things which will probably hit your bank soon -(like uncashed checks), and no flags to see the most up-to-date state of -your finances. - - -File: hledger.info, Node: Code, Next: Description, Prev: Status, Up: Journal - -8.6 Code -======== - -After the status mark, but before the description, you can optionally -write a transaction "code", enclosed in parentheses. This is a good -place to record a check number, or some other important transaction id -or reference number. - - -File: hledger.info, Node: Description, Next: Transaction comments, Prev: Code, Up: Journal - -8.7 Description -=============== - -After the date, status mark and/or code fields, the rest of the line (or -until a comment is begun with ';') is the transaction's description. -Here you can describe the transaction (called the "narration" in -traditional bookkeeping), or you can record a payee/payer name, or you -can leave it empty. - - Transaction descriptions show up in print output and in register -reports, and can be listed with the descriptions command. - - You can query by description with 'desc:DESCREGEX', or pivot on -description with '--pivot desc'. - -* Menu: - -* Payee and note:: - - -File: hledger.info, Node: Payee and note, Up: Description - -8.7.1 Payee and note --------------------- - -Sometimes people want a dedicated payee/payer field that can be queried -and checked more strictly. If you want that, you can write a '|' (pipe) -character in the description. This divides it into a "payee" field on -the left, and a "note" field on the right. (Either can be empty.) - - You can query these with 'payee:PAYEEREGEX' and 'note:NOTEREGEX', -list their values with the payees and notes commands, or pivot on -'payee' or 'note'. - - Note: in transactions with no '|' character, description, payee, and -note all have the same value. Once a '|' is added, they become -distinct. (If you'd like to change this behaviour, please propose it on -the mail list.) - - If you want more strict error checking, you can declare the valid -payee names with payee directives, and then enforce these with hledger -check payees. (Note: because of the above, for this you'll need to -ensure every transaction description contains a '|' and therefore a -checkable payee name, even if it's empty.) - - -File: hledger.info, Node: Transaction comments, Next: Postings, Prev: Description, Up: Journal - -8.8 Transaction comments -======================== - -Text following ';', after a transaction description, and/or on indented -lines immediately below it, form comments for that transaction. They -are reproduced by 'print' but otherwise ignored, except they may contain -tags, which are not ignored. - -2012-01-01 something ; a transaction comment - ; a second line of transaction comment - expenses 1 - assets - - -File: hledger.info, Node: Postings, Next: Account names, Prev: Transaction comments, Up: Journal - -8.9 Postings -============ - -A posting is an addition of some amount to, or removal of some amount -from, an account. Each posting line begins with at least one space or -tab (2 or 4 spaces is common), followed by: - - * (optional) a status character (empty, '!', or '*'), followed by a - space - * (required) an account name (any text, optionally containing *single - spaces*, until end of line or a double space) - * (optional) *two or more spaces* (or tabs) followed by an amount. - - If the amount is positive, it is being added to the account; if -negative, it is being removed from the account. - - The posting amounts in a transaction must sum up to zero, indicating -that the inflows and outflows are equal. We call this a balanced -transaction. (You can read more about the nitty-gritty details of "sum -up to zero" in Transaction balancing below.) - - As a convenience, you can optionally leave one amount blank; hledger -will infer what it should be so as to balance the transaction. - -* Menu: - -* Debits and credits:: -* The two space delimiter:: - - -File: hledger.info, Node: Debits and credits, Next: The two space delimiter, Up: Postings - -8.9.1 Debits and credits ------------------------- - -The traditional accounting concepts of debit and credit of course exist -in hledger, but we represent them with numeric sign, as described above. -Positive and negative posting amounts represent debits and credits -respectively. - - You don't need to remember that, but if you would like to - eg for -helping newcomers or for talking with your accountant - here's a handy -mnemonic: - - _'debit / plus / left / short words'_ -_'credit / minus / right / longer words'_ - - -File: hledger.info, Node: The two space delimiter, Prev: Debits and credits, Up: Postings - -8.9.2 The two space delimiter ------------------------------ - -Be sure to notice the unusual separator between the account name and the -following amount. Because hledger allows account names with spaces in -them, you must separate the account name and amount (if any) by *two or -more spaces* (or tabs). It's easy to forget at first. If you ever see -the amount being treated as part of the account name, you'll know you -probably need to add another space between them. - - -File: hledger.info, Node: Account names, Next: Amounts, Prev: Postings, Up: Journal - -8.10 Account names -================== - -Accounts are the main way of categorising things in hledger. As in -Double Entry Bookkeeping, they can represent real world accounts (such -as a bank account), or more abstract categories such as "money borrowed -from Frank" or "money spent on electricity". - - You can use any account names you like, but we usually start with the -traditional accounting categories, which in english are 'assets', -'liabilities', 'equity', 'revenues', 'expenses'. (You might see these -referred to as A, L, E, R, X for short.) - - For more precise reporting, we usually divide the top level accounts -into more detailed subaccounts, by writing a full colon between account -name parts. For example, from the account names 'assets:bank:checking' -and 'expenses:food', hledger will infer this hierarchy of five accounts: - -assets -assets:bank -assets:bank:checking -expenses -expenses:food - - Shown as an outline, the hierarchical tree structure is more clear: - -assets - bank - checking -expenses - food - - hledger reports can summarise the account tree to any depth, so you -can go as deep as you like with subcategories, but keeping your account -names relatively simple may be best when starting out. - - Account names may be capitalised or not; they may contain letters, -numbers, symbols, or single spaces. Note, when an account name and an -amount are written on the same line, they must be separated by *two or -more spaces* (or tabs). - - Parentheses or brackets enclosing the full account name indicate -virtual postings, described below. Parentheses or brackets internal to -the account name have no special meaning. - - Account names can be altered temporarily or permanently by account -aliases. - - -File: hledger.info, Node: Amounts, Next: Balance assertions, Prev: Account names, Up: Journal - -8.11 Amounts -============ - -After the account name, there is usually an amount. (Remember: between -account name and amount, there must be two or more spaces.) - - hledger's amount format is flexible, supporting several international -formats. Here are some examples. Amounts have a number (the -"quantity"): - -1 - - ..and usually a currency symbol or commodity name (more on this -below), to the left or right of the quantity, with or without a -separating space: - -$1 -4000 AAPL -3 "green apples" - - Amounts can be preceded by a minus sign (or a plus sign, though plus -is the default), The sign can be written before or after a left-side -commodity symbol: - --$1 -$-1 - - One or more spaces between the sign and the number are acceptable -when parsing (but they won't be displayed in output): - -+ $1 -$- 1 - - Scientific E notation is allowed: - -1E-6 -EUR 1E3 - -* Menu: - -* Decimal marks:: -* Digit group marks:: -* Commodity:: -* Costs:: - - -File: hledger.info, Node: Decimal marks, Next: Digit group marks, Up: Amounts - -8.11.1 Decimal marks --------------------- - -A _decimal mark_ can be written as a period or a comma: - -1.23 -1,23 - - Both of these are common in international number formats, so hledger -is not biased towards one or the other. Because hledger also supports -digit group marks (eg thousands separators), this means that a number -like '1,000' or '1.000' containing just one period or comma is -ambiguous. In such cases, hledger by default assumes it is a decimal -mark, and will parse both of those as 1. - - To help hledger parse such ambiguous numbers more accurately, if you -use digit group marks, we recommend declaring the decimal mark -explicitly. The best way is to add a 'decimal-mark' directive at the -top of each data file, like this: - -decimal-mark . - - Or you can declare it per commodity with 'commodity' directives, -described below. - - hledger also accepts numbers like '10.' with no digits after the -decimal mark (and will sometimes display numbers that way to -disambiguate them - see Trailing decimal marks). - - -File: hledger.info, Node: Digit group marks, Next: Commodity, Prev: Decimal marks, Up: Amounts - -8.11.2 Digit group marks ------------------------- - -In the integer part of the amount quantity (left of the decimal mark), -groups of digits can optionally be separated by a _digit group mark_ - a -comma or period (whichever is not used as decimal mark), or a space -(several Unicode space variants, like no-break space, are also -accepted). So these are all valid amounts in a journal file: - - $1,000,000.00 - EUR 2.000.000,00 -INR 9,99,99,999.00 - 1 000 000.00 ; <- ordinary space - 1 000 000.00 ; <- no-break space - - -File: hledger.info, Node: Commodity, Next: Costs, Prev: Digit group marks, Up: Amounts - -8.11.3 Commodity ----------------- - -Amounts in hledger have both a "quantity", which is a signed decimal -number, and a "commodity", which is a currency symbol, stock ticker, or -any word or phrase describing something you are tracking. - - If the commodity name contains non-letters (spaces, numbers, or -punctuation), you must always write it inside double quotes ('"green -apples"', '"ABC123"'). - - If you write just a bare number, that too will have a commodity, with -name '""'; we call that the "no-symbol commodity". - - Actually, hledger combines these single-commodity amounts into more -powerful multi-commodity amounts, which are what it works with most of -the time. A multi-commodity amount could be, eg: '1 USD, 2 EUR, 3.456 -TSLA'. In practice, you will only see multi-commodity amounts in -hledger's output; you can't write them directly in the journal file. - - By default, the format of amounts in the journal influences how -hledger displays them in output. This is explained in Commodity display -style below. - - -File: hledger.info, Node: Costs, Prev: Commodity, Up: Amounts - -8.11.4 Costs ------------- - -After a posting amount, you can note its cost (when buying) or selling -price (when selling) in another commodity, by writing either '@ -UNITPRICE' or '@@ TOTALPRICE' after it. This indicates a conversion -transaction, where one commodity is exchanged for another. - - (You might also see this called "transaction price" in hledger docs, -discussions, or code; that term was directionally neutral and reminded -that it is a price specific to a transaction, but we now just call it -"cost", with the understanding that the transaction could be a purchase -or a sale.) - - Costs are usually written explicitly with '@' or '@@', but can also -be inferred automatically for simple multi-commodity transactions. -Note, if costs are inferred, the order of postings is significant; the -first posting will have a cost attached, in the commodity of the second. - - As an example, here are several ways to record purchases of a foreign -currency in hledger, using the cost notation either explicitly or -implicitly: - - 1. Write the price per unit, as '@ UNITPRICE' after the amount: - - 2009/1/1 - assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each - assets:dollars ; balancing amount is -$135.00 - - 2. Write the total price, as '@@ TOTALPRICE' after the amount: - - 2009/1/1 - assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot - assets:dollars - - 3. Specify amounts for all postings, using exactly two commodities, - and let hledger infer the price that balances the transaction. - Note the effect of posting order: the price is added to first - posting, making it '€100 @@ $135', as in example 2: - - 2009/1/1 - assets:euros €100 ; one hundred euros purchased - assets:dollars $-135 ; for $135 - - Amounts can be converted to cost at report time using the '-B/--cost' -flag; this is discussed more in the Cost reporting section. - - Note that the cost normally should be a positive amount, though it's -not required to be. This can be a little confusing, see discussion at --infer-market-prices: market prices from transactions. - - -File: hledger.info, Node: Balance assertions, Next: Posting comments, Prev: Amounts, Up: Journal - -8.12 Balance assertions -======================= - -hledger supports Ledger-style balance assertions in journal files. -These look like, for example, '= EXPECTEDBALANCE' following a posting's -amount. Eg here we assert the expected dollar balance in accounts a and -b after each posting: - -2013/1/1 - a $1 = $1 - b = $-1 - -2013/1/2 - a $1 = $2 - b $-1 = $-2 - - After reading a journal file, hledger will check all balance -assertions and report an error if any of them fail. Balance assertions -can protect you from, eg, inadvertently disrupting reconciled balances -while cleaning up old entries. You can disable them temporarily with -the '-I/--ignore-assertions' flag, which can be useful for -troubleshooting or for reading Ledger files. (Note: this flag currently -does not disable balance assignments, described below). - -* Menu: - -* Assertions and ordering:: -* Assertions and multiple files:: -* Assertions and costs:: -* Assertions and commodities:: -* Assertions and subaccounts:: -* Assertions and status:: -* Assertions and virtual postings:: -* Assertions and auto postings:: -* Assertions and precision:: -* Assertions and hledger add:: - - -File: hledger.info, Node: Assertions and ordering, Next: Assertions and multiple files, Up: Balance assertions - -8.12.1 Assertions and ordering ------------------------------- - -hledger calculates and checks an account's balance assertions in date -order (and when there are multiple assertions on the same day, in parse -order). Note this is different from Ledger, which checks assertions -always in parse order, ignoring dates. - - This means in hledger you can freely reorder transactions, postings, -or files, and balance assertions will usually keep working. The -exception is when you reorder multiple postings on the same day, to the -same account, which have balance assertions; those will likely need -updating. - - -File: hledger.info, Node: Assertions and multiple files, Next: Assertions and costs, Prev: Assertions and ordering, Up: Balance assertions - -8.12.2 Assertions and multiple files ------------------------------------- - -If an account has transactions appearing in multiple files, balance -assertions can still work - but _only if those files are part of a -hierarchy made by include directives_. - - If the same files are specified with two '-f' options on the command -line, the assertions in the second will not see the balances from the -first. - - To work around this, arrange your files in a hierarchy with -'include'. Or, you could concatenate the files temporarily, and process -them like one big file. - - Why does it work this way ? It might be related to hledger's goal of -stable predictable reports. File hierarchy is considered "permanent", -part of your data, while the order of command line options/arguments is -not. We don't want transient changes to be able to change the meaning -of the data. Eg it would be frustrating if tomorrow all your balance -assertions broke because you wrote command line arguments in a different -order. (Discussion welcome.) - - -File: hledger.info, Node: Assertions and costs, Next: Assertions and commodities, Prev: Assertions and multiple files, Up: Balance assertions - -8.12.3 Assertions and costs ---------------------------- - -Balance assertions ignore costs, and should normally be written without -one: - -2019/1/1 - (a) $1 @ €1 = $1 - - We do allow costs to be written in balance assertion amounts, -however, and print shows them, but they don't affect whether the -assertion passes or fails. This is for backward compatibility -(hledger's close command used to generate balance assertions with -costs), and because balance _assignments_ do use costs (see below). - - -File: hledger.info, Node: Assertions and commodities, Next: Assertions and subaccounts, Prev: Assertions and costs, Up: Balance assertions - -8.12.4 Assertions and commodities ---------------------------------- - -The balance assertions described so far are "*single commodity balance -assertions*": they assert and check the balance in one commodity, -ignoring any others that may be present. This is how balance assertions -work in Ledger also. - - If an account contains multiple commodities, you can assert their -balances by writing multiple postings with balance assertions, one for -each commodity: - -2013/1/1 - usd $-1 - eur €-1 - both - -2013/1/2 - both 0 = $1 - both 0 = €1 - - In hledger you can make a stronger "*sole commodity balance -assertion*" by writing two equals signs ('== EXPECTEDBALANCE'). This -also asserts that there are no other commodities in the account besides -the asserted one (or at least, that their current balance is zero): - -2013/1/1 - usd $-1 == $-1 ; these sole commodity assertions succeed - eur €-1 == €-1 - both ;== $1 ; this one would fail because 'both' contains $ and € - - It's less easy to make a "*sole commodities balance assertion*" (note -the plural) - ie, asserting that an account contains two or more -specified commodities and no others. It can be done by - - 1. isolating each commodity in a subaccount, and asserting those - 2. and also asserting there are no commodities in the parent account - itself: - -2013/1/1 - usd $-1 - eur €-1 - both 0 == 0 ; nothing up my sleeve - both:usd $1 == $1 ; a dollar here - both:eur €1 == €1 ; a euro there - - -File: hledger.info, Node: Assertions and subaccounts, Next: Assertions and status, Prev: Assertions and commodities, Up: Balance assertions - -8.12.5 Assertions and subaccounts ---------------------------------- - -All of the balance assertions above (both '=' and '==') are -"*subaccount-exclusive balance assertions*"; they ignore any balances -that exist in deeper subaccounts. - - In hledger you can make "*subaccount-inclusive balance assertions*" -by adding a star after the equals ('=*' or '==*'): - -2019/1/1 - equity:start - assets:checking $10 - assets:savings $10 - assets $0 ==* $20 ; assets + subaccounts contains $20 and nothing else - - -File: hledger.info, Node: Assertions and status, Next: Assertions and virtual postings, Prev: Assertions and subaccounts, Up: Balance assertions - -8.12.6 Assertions and status ----------------------------- - -Balance assertions always consider postings of all statuses (unmarked, -pending, or cleared); they are not affected by the '-U'/'--unmarked' / -'-P'/'--pending' / '-C'/'--cleared' flags or the 'status:' query. - - -File: hledger.info, Node: Assertions and virtual postings, Next: Assertions and auto postings, Prev: Assertions and status, Up: Balance assertions - -8.12.7 Assertions and virtual postings --------------------------------------- - -Balance assertions always consider both real and virtual postings; they -are not affected by the '--real/-R' flag or 'real:' query. - - -File: hledger.info, Node: Assertions and auto postings, Next: Assertions and precision, Prev: Assertions and virtual postings, Up: Balance assertions - -8.12.8 Assertions and auto postings ------------------------------------ - -Balance assertions _are_ affected by the '--auto' flag, which generates -auto postings, which can alter account balances. Because auto postings -are optional in hledger, accounts affected by them effectively have two -balances. But balance assertions can only test one or the other of -these. So to avoid making fragile assertions, either: - - * assert the balance calculated with '--auto', and always use - '--auto' with that file - * or assert the balance calculated without '--auto', and never use - '--auto' with that file - * or avoid balance assertions on accounts affected by auto postings - (or avoid auto postings entirely). - - -File: hledger.info, Node: Assertions and precision, Next: Assertions and hledger add, Prev: Assertions and auto postings, Up: Balance assertions - -8.12.9 Assertions and precision -------------------------------- - -Balance assertions compare the exactly calculated amounts, which are not -always what is shown by reports. Eg a commodity directive may limit the -display precision, but this will not affect balance assertions. Balance -assertion failure messages show exact amounts. - - -File: hledger.info, Node: Assertions and hledger add, Prev: Assertions and precision, Up: Balance assertions - -8.12.10 Assertions and hledger add ----------------------------------- - -Balance assertions can be included in the amounts given in 'add'. All -types of assertions are supported, and assertions can be used as in a -normal journal file. - - All transactions, not just those that have an explicit assertion, are -validated against the existing assertions in the journal. This means it -is possible for an added transaction to fail even if its assertions are -correct as of the transaction date. - - If this assertion checking is not desired, then it can be disabled -with '-I'. - - However, balance assignments are currently not supported. - - -File: hledger.info, Node: Posting comments, Next: Transaction balancing, Prev: Balance assertions, Up: Journal - -8.13 Posting comments -===================== - -Text following ';', at the end of a posting line, and/or on indented -lines immediately below it, form comments for that posting. They are -reproduced by 'print' but otherwise ignored, except they may contain -tags, which are not ignored. - -2012-01-01 - expenses 1 ; a comment for posting 1 - assets - ; a comment for posting 2 - ; a second comment line for posting 2 - - -File: hledger.info, Node: Transaction balancing, Next: Tags, Prev: Posting comments, Up: Journal - -8.14 Transaction balancing -========================== - -How exactly does hledger decide when a transaction is balanced ? -Especially when it involves costs, which often are not exact, because of -repeating decimals, or imperfect data from financial institutions ? In -each commodity, hledger sums the transaction's posting amounts, after -converting any with costs; then it checks if that sum is zero, when -rounded to a suitable number of decimal digits - which we call the -_balancing precision_. - - Since version 1.50, hledger infers balancing precision in each -transaction from the amounts in that transaction's journal entry (like -Ledger). Ie, when checking the balance of commodity A, it uses the -highest decimal precision seen for A in the journal entry (excluding -cost amounts). This makes transaction balancing robust; any imbalances -must be visibly accounted for in the journal entry, display precision -can be freely increased with '-c', and compatibility with Ledger and -Beancount journals is good. - - Note that hledger versions before 1.50 worked differently: they -allowed display precision to override the balancing precision. This -masked small imbalances and caused fragility (see issue #2402). As a -result, some journal entries (or CSV rules) that worked with hledger -<1.50, are now rejected with an "unbalanced transaction" error. If you -hit this problem, it's easy to fix: - - * You can restore the old behaviour, by adding '--txn-balancing=old' - to the command or to your '~/.hledger.conf' file. This lets you - keep using old journals unchanged, though without the above - benefits. - - * Or you can fix the problem entries (recommended). There are three - ways, use whichever seems best: - - 1. make cost amounts more precise (add more/better decimal - digits) - 2. or make non-cost amounts less precise (remove unnecessary - decimal digits that are raising the precision) - 3. or add a posting to absorb the imbalance (eg - "expenses:rounding". Remember that one posting may omit the - amount; that's convenient here.) - - -File: hledger.info, Node: Tags, Next: Directives, Prev: Transaction balancing, Up: Journal - -8.15 Tags -========= - -Tags are a way to add extra labels or data fields to transactions, -postings, or accounts. They are usually a word or hyphenated word, -immediately followed by a full colon, written within the comment of a -transaction, a posting, or an 'account' directive. (Yes, storing data -in comments is slightly weird!) - - You can write each tag on its own comment line, or multiple tags on -one line, separated by commas. Tags can also have a value, which is any -text after the colon until the next comma or end of line, excluding -surrounding whitespace. (hledger tag values can't contain commas.) If -the same tag name appears multiple times in a comment, each name:value -pair is preserved. - - An example: in this journal there are six tags, one of them with a -value: - -account assets:checking ; accounttag: -account expenses:food - -2017/1/16 bought groceries ; transactiontag: - ; transactiontag2: - assets:checking $-1 - ; posting-tag-1:, (belongs to the posting above) - expenses:food $1 ; posting-tag-2:, posting-tag-3: with a value - -* Menu: - -* Querying with tags:: -* Displaying tags:: -* When to use tags ?:: -* Tag names:: -* Special tags:: - - -File: hledger.info, Node: Querying with tags, Next: Displaying tags, Up: Tags - -8.15.1 Querying with tags -------------------------- - -Tags are most often used to select a subset of data; you can match -tagged things by tag name and or tag value with a 'tag:' query. (See -queries below.) - - When querying for tag names or values, note that postings inherit -tags from their transaction and from their account, and transactions -acquire tags from their postings. So in the example above, - the -assets:checking posting effectively has four tags (one of its own, one -from the account, two from the transaction) - the expenses:food posting -effectively has four tags (two of its own, two from the transaction) - -the transaction effectively has all six tags (two of its own, and two -from each posting) - - -File: hledger.info, Node: Displaying tags, Next: When to use tags ?, Prev: Querying with tags, Up: Tags - -8.15.2 Displaying tags ----------------------- - -You can use the 'tags' command to list tag names or values. - - The 'print' command also shows tags. - - You can use -pivot to display tag values in other reports, in various -ways (eg appended to account names, like pseudo subaccounts). - - -File: hledger.info, Node: When to use tags ?, Next: Tag names, Prev: Displaying tags, Up: Tags - -8.15.3 When to use tags ? -------------------------- - -Tags provide more dimensions of categorisation, complementing accounts -and transaction descriptions. When to use each of these is somewhat a -matter of taste. Accounts have the most built-in support, and regex -queries on descriptions are also quite powerful. So you may not need -tags at all. But if you want to track multiple cross-cutting -categories, they can be a good fit. For example, you could tag -trip-related transactions with 'trip: YEAR:PLACE', without disturbing -your usual account categories. - - -File: hledger.info, Node: Tag names, Next: Special tags, Prev: When to use tags ?, Up: Tags - -8.15.4 Tag names ----------------- - -What is allowed in a tag name ? Currently, most non-whitespace -characters. Eg '😀:' is a valid tag. - - For extra error checking, you can declare valid tag names with the -'tag' directive, and then enforce these with the 'check' command. - - But note that tags are detected quite loosely at present, sometimes -where you didn't intend them. Eg '; see https://foo.com' contains a -'https' tag with value '//foo.com'. - - -File: hledger.info, Node: Special tags, Prev: Tag names, Up: Tags - -8.15.5 Special tags -------------------- - -Some tag names have special significance to hledger. They are explained -elsewhere, but here's a quick reference: - - type -- declares an account's type - date -- overrides a posting's date - date2 -- overrides a posting's secondary date - assert -- appears on txns generated by close --assert - retain -- appears on txns generated by close --retain - start -- appears on txns generated by close --migrate/--close/--open/--assign - t -- appears on postings generated from timedot letters - - generated-transaction -- appears on txns generated by a periodic rule - modified-transaction -- appears on txns which have had auto postings added - generated-posting -- appears on generated postings - cost-posting -- appears on postings which have (or could have) a cost, - and which have equivalent conversion postings in the transaction - conversion-posting -- appears on postings which are to a V/Conversion account - and which have an equivalent cost posting in the transaction - - The second group above (generated-transaction, etc.) are normally -hidden, with a '_' prefix added. This means 'print' doesn't show them -by default; but you can still use them in queries. You can add the -'--verbose-tags' flag to make them visible, which can be useful for -troubleshooting. - - -File: hledger.info, Node: Directives, Next: account directive, Prev: Tags, Up: Journal - -8.16 Directives -=============== - -Besides transactions, there is something else you can put in a 'journal' -file: directives. These are declarations, beginning with a keyword, -that modify hledger's behaviour. Some directives can have more specific -subdirectives, indented below them. hledger's directives are similar to -Ledger's in many cases, but there are also many differences. Directives -are not required, but can be useful. Here are the main directives: - -purpose directive --------------------------------------------------------------------------- -*READING DATA:* -Rewrite account names 'alias' -Comment out sections of the file 'comment' -Declare file's decimal mark, to help 'decimal-mark' -parse amounts accurately -Include other data files 'include' -*GENERATING DATA:* -Generate recurring transactions or '~' -budget goals -Generate extra postings on existing '=' -transactions -*CHECKING FOR ERRORS:* -Define valid entities to provide more 'account', 'commodity', -error checking 'payee', 'tag' -*REPORTING:* -Declare accounts' type and display 'account' -order -Declare commodity display styles 'commodity' -Declare market prices 'P' - -* Menu: - -* Directives and multiple files:: -* Directive effects:: - - -File: hledger.info, Node: Directives and multiple files, Next: Directive effects, Up: Directives - -8.16.1 Directives and multiple files ------------------------------------- - -Directives vary in their scope, ie which journal entries and which input -files they affect. Most often, a directive will affect the following -entries and included files if any, until the end of the current file - -and no further. You might find this inconvenient! For example, 'alias' -directives do not affect parent or sibling files. But there are usually -workarounds; for example, put 'alias' directives in your top-most file, -before including other files. - - The restriction, though it may be annoying at first, is in a good -cause; it allows reports to be stable and deterministic, independent of -the order of input. Without it, reports could show different numbers -depending on the order of -f options, or the positions of include -directives in your files. - - -File: hledger.info, Node: Directive effects, Prev: Directives and multiple files, Up: Directives - -8.16.2 Directive effects ------------------------- - -Here are all hledger's directives, with their effects and scope -summarised - nine main directives, plus four others which we consider -non-essential: - -directivewhat it does ends - at - file - end? ---------------------------------------------------------------------------- -*'account'*Declares an account, for checking all entries in all files; andN - its display order and type. Subdirectives: any text, ignored. -*'alias'*Rewrites account names, in following entries until end of Y - current file or 'end aliases'. Command line equivalent: - '--alias' -*'comment'*Ignores part of the journal file, until end of current file orY - 'end comment'. -*'commodity'*Declares up to four things: 1. a commodity symbol, for checkingN,N,Y,Y - all amounts in all files 2. the display style for all amounts - of this commodity 3. the decimal mark for parsing amounts of - this commodity, in the rest of this file and its children, if - there is no 'decimal-mark' directive 4. the precision to use - for balanced-transaction checking in this commodity, in this - file and its children. Takes precedence over 'D'. - Subdirectives: 'format' (ignored). Command line equivalent: - '-c/--commodity-style' -*'decimal-mark'*Declares the decimal mark, for parsing amounts of all Y - commodities in following entries until next 'decimal-mark' or - end of current file. Included files can override. Takes - precedence over 'commodity' and 'D'. -*'include'*Includes entries and directives from another file, as if theyN - were written inline. Command line alternative: multiple - '-f/--file' -*'payee'*Declares a payee name, for checking all entries in all files. N -*'P'*Declares the market price of a commodity on some date, for value N - reports. -*'~'*Declares a periodic transaction rule that generates future N -(tilde)transactions with '--forecast' and budget goals with 'balance - --budget'. -Other -syntax: -*'applyPrepends a common parent account to all account names, in Y -account'*following entries until end of current file or 'end apply - account'. -*'D'*Sets a default commodity to use for no-symbol amounts;and, if Y,Y,N,N - there is no 'commodity' directive for this commodity: its - decimal mark, balancing precision, and display style, as above. -*'Y'*Sets a default year to use for any yearless dates, in following Y - entries until end of current file. -*'='*Declares an auto posting rule that generates extra postings on partly -(equals)matched transactions with '--auto', in current, parent, and - child files (but not sibling files, see #1212). -*OtherOther directives from Ledger's file format are accepted but -Ledgerignored. -directives* - - -File: hledger.info, Node: account directive, Next: alias directive, Prev: Directives, Up: Journal - -8.17 'account' directive -======================== - -'account' directives can be used to declare accounts (ie, the places -that amounts are transferred from and to). Though not required, these -declarations can provide several benefits: - - * They can document your intended chart of accounts, providing a - reference. - * They can store additional account information as comments, or as - tags which can be used to filter or pivot reports. - * They can restrict which accounts may be posted to by transactions, - eg in strict mode, which helps prevent errors. - * They influence account display order in reports, allowing - non-alphabetic sorting (eg Revenues to appear above Expenses). - * They can help hledger know your accounts' types (asset, liability, - equity, revenue, expense), enabling reports like balancesheet and - incomestatement. - * They help with account name completion (in hledger add, - hledger-web, hledger-iadd, ledger-mode, etc.) - - They are written as the word 'account' followed by a hledger-style -account name. Eg: - -account assets:bank:checking - - Ledger-style indented subdirectives are also accepted, but ignored: - -account assets:bank:checking - format subdirective ; currently ignored - -* Menu: - -* Account comments:: -* Account error checking:: -* Account display order:: -* Account types:: - - -File: hledger.info, Node: Account comments, Next: Account error checking, Up: account directive - -8.17.1 Account comments ------------------------ - -Text following *two or more spaces* and ';' at the end of an account -directive line, and/or following ';' on indented lines immediately below -it, form comments for that account. They are ignored except they may -contain tags, which are not ignored. - - The two-space requirement for same-line account comments is because -';' is allowed in account names. - -account assets:bank:checking ; same-line comment, at least 2 spaces before the semicolon - ; next-line comment - ; some tags - type:A, acctnum:12345 - - -File: hledger.info, Node: Account error checking, Next: Account display order, Prev: Account comments, Up: account directive - -8.17.2 Account error checking ------------------------------ - -By default, accounts need not be declared; they come into existence when -a posting references them. This is convenient, but it means hledger -can't warn you when you mis-spell an account name in the journal. -Usually you'll find that error later, as an extra account in balance -reports, or an incorrect balance when reconciling. - - In strict mode, enabled with the '-s'/'--strict' flag, or when you -run 'hledger check accounts', hledger will report an error if any -transaction uses an account name that has not been declared by an -account directive. Some notes: - - * The declaration is case-sensitive; transactions must use the - correct account name capitalisation. - * The account directive's scope is "whole file and below" (see - directives). This means it affects all of the current file, and - any files it includes, but not parent or sibling files. The - position of account directives within the file does not matter, - though it's usual to put them at the top. - * Accounts can only be declared in 'journal' files, but will affect - included files of all types. - * It's currently not possible to declare "all possible subaccounts" - with a wildcard; every account posted to must be declared. - * If you use the -infer-equity flag, you will also need declarations - for the account names it generates. - - -File: hledger.info, Node: Account display order, Next: Account types, Prev: Account error checking, Up: account directive - -8.17.3 Account display order ----------------------------- - -Account directives also cause hledger to display accounts in a -particular order, not just alphabetically. Eg, here is a conventional -ordering for the top-level accounts: - -account assets -account liabilities -account equity -account revenues -account expenses - - Now hledger displays them in that order: - -$ hledger accounts -assets -liabilities -equity -revenues -expenses - - If there are undeclared accounts, those will be displayed last, in -alphabetical order. - - Sorting is done within each group of sibling accounts, at each level -of the account tree. Eg, a declaration like 'account parent:child' -influences 'child''s position among its siblings. - - Note, it does not affect 'parent''s position; for that, you need an -'account parent' declaration. - - Sibling accounts are always displayed together; hledger won't display -'x:y' in between 'a:b' and 'a:c'. - - An account directive both declares an account as a valid posting -target, and declares its display order; you can't easily do one without -the other. - - -File: hledger.info, Node: Account types, Prev: Account display order, Up: account directive - -8.17.4 Account types --------------------- - -hledger knows that in accounting there are three main account types: - -'Asset' 'A' things you own -'Liability' 'L' things you owe -'Equity' 'E' owner's investment, balances the two above - - and two more representing changes in these: - -'Revenue' 'R' inflows (also known as 'Income') -'Expense' 'X' outflows - - hledger also uses a couple of subtypes: - -'Cash' 'C' liquid assets -'Conversion' 'V' commodity conversions equity - - As a convenience, hledger will detect these types automatically from -english account names. But it's better to declare them explicitly by -adding a 'type:' tag in the account directives. The tag's value can be -any of the types or one-letter abbreviations above. - - Here is a typical set of account type declarations. Subaccounts will -inherit their parent's type, or can override it: - -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 - - This enables the easy balancesheet, balancesheetequity, cashflow and -incomestatement reports, and querying by type:. - - Tips: - - * You can list accounts and their types, for troubleshooting: - - $ hledger accounts --types [ACCTPAT] [type:TYPECODES] [-DEPTH] [--positions] - - * It's a good idea to declare at least one account for each account - type. Having some types declared and some inferred can disrupt - certain reports. - - * The rules for inferring types from account names are as follows - (using Regular expressions). - If they don't work for you, just ignore them and declare your types - with 'type:' tags. - - If account's name contains this case insensitive 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 - - * As mentioned above, subaccounts will inherit a type from their - parent account. To be precise, an account's type is decided by the - first of these that exists: - - 1. A 'type:' declaration for this account. - 2. A 'type:' declaration in the parent accounts above it, - preferring the nearest. - 3. An account type inferred from this account's name. - 4. An account type inferred from a parent account's name, - preferring the nearest parent. - 5. Otherwise, it will have no type. - - * Account aliases can disrupt account types. - - -File: hledger.info, Node: alias directive, Next: commodity directive, Prev: account directive, Up: Journal - -8.18 'alias' directive -====================== - -You can define account alias rules which rewrite your account names, or -parts of them, before generating reports. This can be useful for: - - * expanding shorthand account names to their full form, allowing - easier data entry and a less verbose journal - * adapting old journals to your current chart of accounts - * experimenting with new account organisations, like a new hierarchy - * combining two accounts into one, eg to see their sum or difference - on one line - * customising reports - - Account aliases also rewrite account names in account directives. -They do not affect account names being entered via hledger add or -hledger-web. - - Account aliases are very powerful. They are generally easy to use -correctly, but you can also generate invalid account names with them; -more on this below. - - See also Rewrite account names. - -* Menu: - -* Basic aliases:: -* Regex aliases:: -* Combining aliases:: -* Aliases and multiple files:: -* end aliases directive:: -* Aliases can generate bad account names:: -* Aliases and account types:: - - -File: hledger.info, Node: Basic aliases, Next: Regex aliases, Up: alias directive - -8.18.1 Basic aliases --------------------- - -To set an account alias, use the 'alias' directive in your journal file. -This affects all subsequent journal entries in the current file or its -included files (but note: not sibling or parent files). The spaces -around the = are optional: - -alias OLD = NEW - - Or, you can use the '--alias 'OLD=NEW'' option on the command line. -This affects all entries. It's useful for trying out aliases -interactively. - - OLD and NEW are case sensitive full account names. hledger will -replace any occurrence of the old account name with the new one. -Subaccounts are also affected. Eg: - -alias checking = assets:bank:wells fargo:checking -; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" - - -File: hledger.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: alias directive - -8.18.2 Regex aliases --------------------- - -There is also a more powerful variant that uses a regular expression, -indicated by wrapping the pattern in forward slashes. (This is the only -place where hledger requires forward slashes around a regular -expression.) - - Eg: - -alias /REGEX/ = REPLACEMENT - - or: - -$ hledger --alias '/REGEX/=REPLACEMENT' ... - - Any part of an account name matched by REGEX will be replaced by -REPLACEMENT. REGEX is case-insensitive as usual. - - If you need to match a forward slash, escape it with a backslash, eg -'/\/=:'. - - If REGEX contains parenthesised match groups, these can be referenced -by the usual backslash and number in REPLACEMENT: - -alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3 -; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" - - REPLACEMENT continues to the end of line (or on command line, to end -of option argument), so it can contain trailing whitespace. - - -File: hledger.info, Node: Combining aliases, Next: Aliases and multiple files, Prev: Regex aliases, Up: alias directive - -8.18.3 Combining aliases ------------------------- - -You can define as many aliases as you like, using journal directives -and/or command line options. - - Recursive aliases - where an account name is rewritten by one alias, -then by another alias, and so on - are allowed. Each alias sees the -effect of previously applied aliases. - - In such cases it can be important to understand which aliases will be -applied and in which order. For (each account name in) each journal -entry, we apply: - - 1. 'alias' directives preceding the journal entry, most recently - parsed first (ie, reading upward from the journal entry, bottom to - top) - 2. '--alias' options, in the order they appeared on the command line - (left to right). - - In other words, for (an account name in) a given journal entry: - - * the nearest alias declaration before/above the entry is applied - first - * the next alias before/above that will be be applied next, and so on - * aliases defined after/below the entry do not affect it. - - This gives nearby aliases precedence over distant ones, and helps -provide semantic stability - aliases will keep working the same way -independent of which files are being read and in which order. - - In case of trouble, adding '--debug=6' to the command line will show -which aliases are being applied when. - - -File: hledger.info, Node: Aliases and multiple files, Next: end aliases directive, Prev: Combining aliases, Up: alias directive - -8.18.4 Aliases and multiple files ---------------------------------- - -As explained at Directives and multiple files, 'alias' directives do not -affect parent or sibling files. Eg in this command, - -hledger -f a.aliases -f b.journal - - account aliases defined in a.aliases will not affect b.journal. -Including the aliases doesn't work either: - -include a.aliases - -2023-01-01 ; not affected by a.aliases - foo 1 - bar - - This means that account aliases should usually be declared at the -start of your top-most file, like this: - -alias foo=Foo -alias bar=Bar - -2023-01-01 ; affected by aliases above - foo 1 - bar - -include c.journal ; also affected - - -File: hledger.info, Node: end aliases directive, Next: Aliases can generate bad account names, Prev: Aliases and multiple files, Up: alias directive - -8.18.5 'end aliases' directive ------------------------------- - -You can clear (forget) all currently defined aliases (seen in the -journal so far, or defined on the command line) with this directive: - -end aliases - - -File: hledger.info, Node: Aliases can generate bad account names, Next: Aliases and account types, Prev: end aliases directive, Up: alias directive - -8.18.6 Aliases can generate bad account names ---------------------------------------------- - -Be aware that account aliases can produce malformed account names, which -could cause confusing reports or invalid 'print' output. For example, -you could erase all account names: - -2021-01-01 - a:aa 1 - b - -$ hledger print --alias '/.*/=' -2021-01-01 - 1 - - The above 'print' output is not a valid journal. Or you could insert -an illegal double space, causing 'print' output that would give a -different journal when reparsed: - -2021-01-01 - old 1 - other - -$ hledger print --alias old="new USD" | hledger -f- print -2021-01-01 - new USD 1 - other - - -File: hledger.info, Node: Aliases and account types, Prev: Aliases can generate bad account names, Up: alias directive - -8.18.7 Aliases and account types --------------------------------- - -If an account with a type declaration (see Declaring accounts > Account -types) is renamed by an alias, normally the account type remains in -effect. - - However, renaming in a way that reshapes the account tree (eg -renaming parent accounts but not their children, or vice versa) could -prevent child accounts from inheriting the account type of their -parents. - - Secondly, if an account's type is being inferred from its name, -renaming it by an alias could prevent or alter that. - - If you are using account aliases and the 'type:' query is not -matching accounts as you expect, try troubleshooting with the accounts -command, eg something like: - -$ hledger accounts --types -1 --alias assets=bassetts - - -File: hledger.info, Node: commodity directive, Next: decimal-mark directive, Prev: alias directive, Up: Journal - -8.19 'commodity' directive -========================== - -The 'commodity' directive performs several functions: - - 1. It declares which commodity symbols may be used in the journal, - enabling useful error checking with strict mode or the check - command. See Commodity error checking below. - - 2. It declares how all amounts in this commodity should be displayed, - eg how many decimals to show. See Commodity display style above. - - 3. (If no 'decimal-mark' directive is in effect:) It sets the decimal - mark to expect (period or comma) when parsing amounts in this - commodity, in this file and files it includes, from the directive - until end of current file. See Decimal marks above. - - 4. It declares the precision with which this commodity's amounts - should be compared when checking for balanced transactions, - anywhere in this file and files it includes, until end of current - file. - - Declaring commodities solves several common parsing/display problems, -so we recommend it. - - Note that effects 3 and 4 above end at the end of the directive's -file, and will not affect sibling or parent files. So if you are -relying on them (especially 4) and using multiple files, placing your -commodity directives in a top-level parent file might be important. Or, -keep your decimal marks unambiguous and your entries well balanced and -precise. - - (Related: #793) - -* Menu: - -* Commodity directive syntax:: -* Commodity error checking:: - - -File: hledger.info, Node: Commodity directive syntax, Next: Commodity error checking, Up: commodity directive - -8.19.1 Commodity directive syntax ---------------------------------- - -A commodity directive is normally the word 'commodity' followed by a -sample amount (and optionally a comment). Only the amount's symbol and -the number's format is significant. Eg: - -commodity $1000.00 -commodity 1.000,00 EUR -commodity 1 000 000.0000 ; the no-symbol commodity - - Commodities do not have tags (tags in the comment will be ignored). - - A commodity directive's sample amount must always include a period or -comma decimal mark (this rule helps disambiguate decimal marks and digit -group marks). If you don't want to show any decimal digits, write the -decimal mark at the end: - -commodity 1000. AAAA ; show AAAA with no decimals - - Commodity symbols containing spaces, numbers, or punctuation must be -enclosed in double quotes, as usual: - -commodity 1.0000 "AAAA 2023" - - Commodity directives normally include a sample amount, but can -declare only a symbol (ie, just function 1 above): - -commodity $ -commodity INR -commodity "AAAA 2023" -commodity "" ; the no-symbol commodity - - Commodity directives may also be written with an indented 'format' -subdirective, as in Ledger. The symbol is repeated and must be the same -in both places. Other subdirectives are currently ignored: - -; display indian rupees with currency name on the left, -; thousands, lakhs and crores comma-separated, -; period as decimal point, and two decimal places. -commodity INR - format INR 1,00,00,000.00 - an unsupported subdirective ; ignored by hledger - - -File: hledger.info, Node: Commodity error checking, Prev: Commodity directive syntax, Up: commodity directive - -8.19.2 Commodity error checking -------------------------------- - -In strict mode ('-s'/'--strict') (or when you run 'hledger check -commodities'), hledger will report an error if an undeclared commodity -symbol is used. (With one exception: zero amounts are always allowed to -have no commodity symbol.) It works like account error checking -(described above). - - -File: hledger.info, Node: decimal-mark directive, Next: include directive, Prev: commodity directive, Up: Journal - -8.20 'decimal-mark' directive -============================= - -You can use a 'decimal-mark' directive - usually one per file, at the -top of the file - to declare which character represents a decimal mark -when parsing amounts in this file. It can look like - -decimal-mark . - - or - -decimal-mark , - - This prevents any ambiguity when parsing numbers in the file, so we -recommend it, especially if the file contains digit group marks (eg -thousands separators). - - -File: hledger.info, Node: include directive, Next: P directive, Prev: decimal-mark directive, Up: Journal - -8.21 'include' directive -======================== - -You can pull in the content of additional files by writing an include -directive, like this: - -include SOMEFILE - - This has the same effect as if SOMEFILE's content was inlined at this -point. (With any include directives in SOMEFILE processed similarly, -recursively.) - - Only journal files can include other files. They can include -journal, timeclock or timedot files, but not CSV files. - - If the file path begins with a tilde, that means your home directory: -'include ~/main.journal'. - - If it begins with a slash, it is an absolute path: 'include -/home/user/main.journal'. Otherwise it is relative to the including -file's folder: 'include ../finances/main.journal'. - - Also, the path may have a file type prefix to force a specific file -format, overriding the file extension(s) (as described in Data formats): -'include timedot:notes/2023.md'. - - The path may contain glob patterns to match multiple files. -hledger's globs are similar to zsh's: '?' to match any character; -'[a-z]' to match any character in a range; '*' to match zero or more -characters that aren't a path separator (like '/'); '**' to match zero -or more subdirectories and/or zero or more characters at the start of a -file name; etc. Also, hledger's globs always exclude the including file -itself. So, you can do - - * 'include *.journal' to include all other journal files in the - current directory (excluding dot files) - * 'include **.journal' to include all other journal files in this - directory and below (excluding dot directories/files) - * 'include timelogs/2???.timedot' to include all timedot files named - like a year number. - - There is a limitation: hledger's globs always exclude paths involving -dot files or dot directories. This is a workaround for unavoidable dot -directory traversal; you can disable it and revert to older behaviour -with the '--old-glob' flag, for now. - - If you are using many, or deeply nested, include files, and have an -error that's hard to pinpoint: a good troubleshooting command is -'hledger files --debug=6' (or 7). - - -File: hledger.info, Node: P directive, Next: payee directive, Prev: include directive, Up: Journal - -8.22 'P' directive -================== - -The 'P' directive declares a market price, which is a conversion rate -between two commodities on a certain date. This allows value reports to -convert amounts of one commodity to their value in another, on or after -that date. These prices are often obtained from a stock exchange, -cryptocurrency exchange, the or foreign exchange market. - - The format is: - -P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT - - DATE is a simple date, COMMODITY1SYMBOL is the symbol of the -commodity being priced, and COMMODITY2AMOUNT is the amount (symbol and -quantity) of commodity 2 that one unit of commodity 1 is worth on this -date. Examples: - -# one euro was worth $1.35 from 2009-01-01 onward: -P 2009-01-01 € $1.35 - -# and $1.40 from 2010-01-01 onward: -P 2010-01-01 € $1.40 - - The '-V', '-X' and '--value' flags use these market prices to show -amount values in another commodity. See Value reporting. - - -File: hledger.info, Node: payee directive, Next: tag directive, Prev: P directive, Up: Journal - -8.23 'payee' directive -====================== - -'payee PAYEE NAME' - - This directive can be used to declare a limited set of payees which -may appear in transaction descriptions. The "payees" check will report -an error if any transaction refers to a payee that has not been -declared. Eg: - -payee Whole Foods ; a comment - - Payees do not have tags (tags in the comment will be ignored). - - To declare the empty payee name, use '""'. - -payee "" - - Ledger-style indented subdirectives, if any, are currently ignored. - - -File: hledger.info, Node: tag directive, Next: Periodic transactions, Prev: payee directive, Up: Journal - -8.24 'tag' directive -==================== - -'tag TAGNAME' - - This directive can be used to declare a limited set of tag names -allowed in tags. TAGNAME should be a valid tag name (no spaces). Eg: - -tag item-id - - Any indented subdirectives are currently ignored. - - The "tags" check will report an error if any undeclared tag name is -used. It is quite easy to accidentally create a tag through normal use -of colons in comments; if you want to prevent this, you can declare and -check your tags . - - -File: hledger.info, Node: Periodic transactions, Next: Auto postings, Prev: tag directive, Up: Journal - -8.25 Periodic transactions -========================== - -The '~' directive declares a "periodic rule" which generates temporary -extra transactions, usually recurring at some interval, when hledger is -run with the '--forecast' flag. These "forecast transactions" are -useful for forecasting future activity. They exist only for the -duration of the report, and only when '--forecast' is used; they are not -saved in the journal file by hledger. - - Periodic rules also have a second use: with the '--budget' flag they -set budget goals for budgeting. - - Periodic rules can be a little tricky, so before you use them, read -this whole section, or at least the following tips: - - 1. Two spaces accidentally added or omitted will cause you trouble - - read about this below. - 2. For troubleshooting, show the generated transactions with 'hledger - print --forecast tag:generated' or 'hledger register --forecast - tag:generated'. - 3. Forecasted transactions will begin only after the last - non-forecasted transaction's date. - 4. Forecasted transactions will end 6 months from today, by default. - See below for the exact start/end rules. - 5. period expressions can be tricky. Their documentation needs - improvement, but is worth studying. - 6. Some period expressions with a repeating interval must begin on a - natural boundary of that interval. Eg in 'weekly from DATE', DATE - must be a monday. '~ weekly from 2019/10/1' (a tuesday) will give - an error. - 7. Other period expressions with an interval are automatically - expanded to cover a whole number of that interval. (This is done - to improve reports, but it also affects periodic transactions. - Yes, it's a bit inconsistent with the above.) Eg: '~ every 10th - day of month from 2023/01', which is equivalent to '~ every 10th - day of month from 2023/01/01', will be adjusted to start on - 2019/12/10. - -* Menu: - -* Periodic rule syntax:: -* Periodic rules and relative dates:: -* Two spaces between period expression and description!:: - - -File: hledger.info, Node: Periodic rule syntax, Next: Periodic rules and relative dates, Up: Periodic transactions - -8.25.1 Periodic rule syntax ---------------------------- - -A periodic transaction rule looks like a normal journal entry, with the -date replaced by a tilde ('~') followed by a period expression -(mnemonic: '~' looks like a recurring sine wave.): - -# every first of month -~ monthly - expenses:rent $2000 - assets:bank:checking - -# every 15th of month in 2023's first quarter: -~ monthly from 2023-04-15 to 2023-06-16 - expenses:utilities $400 - assets:bank:checking - - The period expression is the same syntax used for specifying -multi-period reports, just interpreted differently; there, it specifies -report periods; here it specifies recurrence dates (the periods' start -dates). - - -File: hledger.info, Node: Periodic rules and relative dates, Next: Two spaces between period expression and description!, Prev: Periodic rule syntax, Up: Periodic transactions - -8.25.2 Periodic rules and relative dates ----------------------------------------- - -Partial or relative dates (like '12/31', '25', 'tomorrow', 'last week', -'next quarter') are usually not recommended in periodic rules, since the -results will change as time passes. If used, they will be interpreted -relative to, in order of preference: - - 1. the first day of the default year specified by a recent 'Y' - directive - 2. or the date specified with '--today' - 3. or the date on which you are running the report. - - They will not be affected at all by report period or forecast period -dates. - - -File: hledger.info, Node: Two spaces between period expression and description!, Prev: Periodic rules and relative dates, Up: Periodic transactions - -8.25.3 Two spaces between period expression and description! ------------------------------------------------------------- - -If the period expression is followed by a transaction description, these -must be separated by *two or more spaces*. This helps hledger know -where the period expression ends, so that descriptions can not -accidentally alter their meaning, as in this example: - -; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2023" -; || -; vv -~ every 2 months in 2023, we will review - assets:bank:checking $1500 - income:acme inc - - So, - - * Do write two spaces between your period expression and your - transaction description, if any. - * Don't accidentally write two spaces in the middle of your period - expression. - - -File: hledger.info, Node: Auto postings, Next: Other syntax, Prev: Periodic transactions, Up: Journal - -8.26 Auto postings -================== - -The '=' directive declares an "auto posting rule", which adds extra -postings to existing transactions. (Remember, postings are the account -name & amount lines below a transaction's date & description.) - - In the journal, an auto posting rule looks quite like a transaction, -but instead of date and description it has '=' (mnemonic: "match") and a -query, like this: - -= QUERY - ACCOUNT AMOUNT - ... - - Queries are just like command line queries; an account name substring -is most common. Query terms containing spaces should be enclosed in -single or double quotes. - - Each '=' rule works like this: when hledger is run with the '--auto' -flag, wherever the QUERY matches a posting in the journal, the rule's -postings are added to that transaction, immediately below the matched -posting. Note these generated postings are temporary, existing only for -the duration of the report, and only when '--auto' is used; they are not -saved in the journal file by hledger. - - The postings can contain the special string '%account' which will be -expanded to the account name of the matched account. - - Generated postings' amounts can depend on the matched posting's -amount. So auto postings can be useful for, eg, adding tax postings -with a standard percentage. AMOUNT can be: - - * a number with no commodity symbol, like '2'. The matched posting's - commodity symbol will be added to this. - - * a normal amount with a commodity symbol, like '$2'. This will be - used as-is. - - * an asterisk followed by a number, like '*2'. This will multiply - the matched posting's amount (and total price, if any) by the - number. - - * an asterisk followed by an amount with commodity symbol, like - '*$2'. This multiplies and also replaces the commodity symbol with - this new one. - - Some examples: - -; every time I buy food, schedule a dollar donation -= expenses:food - (liabilities:charity) $-1 - -; when I buy a gift, also deduct that amount from a budget envelope subaccount -= expenses:gifts - assets:checking:gifts *-1 - assets:checking *1 - -2017/12/1 - expenses:food $10 - assets:checking - -2017/12/14 - expenses:gifts $20 - assets:checking - -$ hledger print --auto -2017-12-01 - expenses:food $10 - assets:checking - (liabilities:charity) $-1 - -2017-12-14 - expenses:gifts $20 - assets:checking - assets:checking:gifts -$20 - assets:checking $20 - - Note that depending fully on generated data such as this has some -drawbacks - it's less portable, less future-proof, less auditable by -others, and less robust (eg your balance assertions will depend on -whether you use or don't use '--auto'). An alternative is to use auto -postings in "one time" fashion - use them to help build a complex -journal entry, view it with 'hledger print --auto', and then copy that -output into the journal file to make it permanent. - -* Menu: - -* Auto postings and multiple files:: -* Auto postings and dates:: -* Auto postings and transaction balancing / inferred amounts / balance assertions:: -* Auto posting tags:: -* Auto postings on forecast transactions only:: - - -File: hledger.info, Node: Auto postings and multiple files, Next: Auto postings and dates, Up: Auto postings - -8.26.1 Auto postings and multiple files ---------------------------------------- - -An auto posting rule can affect any transaction in the current file, or -in any parent file or child file. Note, currently it will not affect -sibling files (when multiple '-f'/'--file' are used - see #1212). - - -File: hledger.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Prev: Auto postings and multiple files, Up: Auto postings - -8.26.2 Auto postings and dates ------------------------------- - -A posting date (or secondary date) in the matched posting, or (taking -precedence) a posting date in the auto posting rule itself, will also be -used in the generated posting. - - -File: hledger.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Next: Auto posting tags, Prev: Auto postings and dates, Up: Auto postings - -8.26.3 Auto postings and transaction balancing / inferred amounts / -------------------------------------------------------------------- - -balance assertions Currently, auto postings are added: - - * after missing amounts are inferred, and transactions are checked - for balancedness, - * but before balance assertions are checked. - - Note this means that journal entries must be balanced both before and -after auto postings are added. This changed in hledger 1.12+; see #893 -for background. - - This also means that you cannot have more than one auto-posting with -a missing amount applied to a given transaction, as it will be unable to -infer amounts. - - -File: hledger.info, Node: Auto posting tags, Next: Auto postings on forecast transactions only, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings - -8.26.4 Auto posting tags ------------------------- - -Automated postings will have some extra tags: - - * 'generated-posting:= QUERY' - shows this was generated by an auto - posting rule, and the query - * '_generated-posting:= QUERY' - a hidden tag, which does not appear - in hledger's output. This can be used to match postings generated - "just now", rather than generated in the past and saved to the - journal. - - Also, any transaction that has been changed by auto posting rules -will have these tags added: - - * 'modified:' - this transaction was modified - * '_modified:' - a hidden tag not appearing in the comment; this - transaction was modified "just now". - - -File: hledger.info, Node: Auto postings on forecast transactions only, Prev: Auto posting tags, Up: Auto postings - -8.26.5 Auto postings on forecast transactions only --------------------------------------------------- - -Tip: you can can make auto postings that will apply to forecast -transactions but not recorded transactions, by adding -'tag:_generated-transaction' to their QUERY. This can be useful when -generating new journal entries to be saved in the journal. - - -File: hledger.info, Node: Other syntax, Prev: Auto postings, Up: Journal - -8.27 Other syntax -================= - -hledger journal format supports quite a few other features, mainly to -make interoperating with or converting from Ledger easier. Note some of -the features below are powerful and can be useful in special cases, but -in general, features in this section are considered less important or -even not recommended for most users. Downsides are mentioned to help -you decide if you want to use them. - -* Menu: - -* Balance assignments:: -* Bracketed posting dates:: -* D directive:: -* apply account directive:: -* Y directive:: -* Secondary dates:: -* Star comments:: -* Valuation expressions:: -* Virtual postings:: -* Other Ledger directives:: -* Other cost/lot notations:: - - -File: hledger.info, Node: Balance assignments, Next: Bracketed posting dates, Up: Other syntax - -8.27.1 Balance assignments --------------------------- - -Ledger-style balance assignments are also supported. These are like -balance assertions, but with no posting amount on the left side of the -equals sign; instead it is calculated automatically so as to satisfy the -assertion. This can be a convenience during data entry, eg when setting -opening balances: - -; starting a new journal, set asset account balances -2016/1/1 opening balances - assets:checking = $409.32 - assets:savings = $735.24 - assets:cash = $42 - equity:opening balances - - or when adjusting a balance to reality: - -; no cash left; update balance, record any untracked spending as a generic expense -2016/1/15 - assets:cash = $0 - expenses:misc - - The calculated amount depends on the account's balance in the -commodity at that point (which depends on the previously-dated postings -of the commodity to that account since the last balance assertion or -assignment). - - Downsides: using balance assignments makes your journal less -explicit; to know the exact amount posted, you have to run hledger or do -the calculations yourself, instead of just reading it. Also balance -assignments' forcing of balances can hide errors. These things make -your financial data less portable, less future-proof, and less -trustworthy in an audit. - -* Menu: - -* Balance assignments and costs:: -* Balance assignments and multiple files:: - - -File: hledger.info, Node: Balance assignments and costs, Next: Balance assignments and multiple files, Up: Balance assignments - -8.27.1.1 Balance assignments and costs -...................................... - -A cost in a balance assignment will cause the calculated amount to have -that cost attached: - -2019/1/1 - (a) = $1 @ €2 - -$ hledger print --explicit -2019-01-01 - (a) $1 @ €2 = $1 @ €2 - - -File: hledger.info, Node: Balance assignments and multiple files, Prev: Balance assignments and costs, Up: Balance assignments - -8.27.1.2 Balance assignments and multiple files -............................................... - -Balance assignments handle multiple files like balance assertions. They -see balance from other files previously included from the current file, -but not from previous sibling or parent files. - - -File: hledger.info, Node: Bracketed posting dates, Next: D directive, Prev: Balance assignments, Up: Other syntax - -8.27.2 Bracketed posting dates ------------------------------- - -For setting posting dates and secondary posting dates, Ledger's -bracketed date syntax is also supported: '[DATE]', '[DATE=DATE2]' or -'[=DATE2]' in posting comments. hledger will attempt to parse any -square-bracketed sequence of the '0123456789/-.=' characters in this -way. With this syntax, DATE infers its year from the transaction and -DATE2 infers its year from DATE. - - Downsides: another syntax to learn, redundant with hledger's -'date:'/'date2:' tags, and confusingly similar to Ledger's lot date -syntax. - - -File: hledger.info, Node: D directive, Next: apply account directive, Prev: Bracketed posting dates, Up: Other syntax - -8.27.3 'D' directive --------------------- - -'D AMOUNT' - - This directive sets a default commodity, to be used for any -subsequent commodityless amounts (ie, plain numbers) seen while parsing -the journal. This effect lasts until the next 'D' directive, or the end -of the current file. - - For compatibility/historical reasons, 'D' also acts like a -'commodity' directive (setting the commodity's decimal mark for parsing -and display style for output). So its argument is not just a commodity -symbol, but a full amount demonstrating the style. The amount must -include a decimal mark (either period or comma). Eg: - -; commodity-less amounts should be treated as dollars -; (and displayed with the dollar sign on the left, thousands separators and two decimal places) -D $1,000.00 - -1/1 - a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00 - b - - Interactions with other directives: - - For setting a commodity's display style, a 'commodity' directive has -highest priority, then a 'D' directive. - - For detecting a commodity's decimal mark during parsing, -'decimal-mark' has highest priority, then 'commodity', then 'D'. - - For checking commodity symbols with the check command, a 'commodity' -directive is required ('hledger check commodities' ignores 'D' -directives). - - Downsides: omitting commodity symbols makes your financial data less -explicit, less portable, and less trustworthy in an audit. It is -usually an unsustainable shortcut; sooner or later you will want to -track multiple commodities. D is overloaded with functions redundant -with 'commodity' and 'decimal-mark'. And it works differently from -Ledger's 'D'. - - -File: hledger.info, Node: apply account directive, Next: Y directive, Prev: D directive, Up: Other syntax - -8.27.4 'apply account' directive --------------------------------- - -This directive sets a default parent account, which will be prepended to -all accounts in following entries, until an 'end apply account' -directive or end of current file. Eg: - -apply account home - -2010/1/1 - food $10 - cash - -end apply account - - is equivalent to: - -2010/01/01 - home:food $10 - home:cash $-10 - - 'account' directives are also affected, and so is any 'include'd -content. - - Account names entered via hledger add or hledger-web are not -affected. - - Account aliases, if any, are applied after the parent account is -prepended. - - Downsides: this can make your financial data less explicit, less -portable, and less trustworthy in an audit. - - -File: hledger.info, Node: Y directive, Next: Secondary dates, Prev: apply account directive, Up: Other syntax - -8.27.5 'Y' directive --------------------- - -'Y YEAR' - - or (deprecated backward-compatible forms): - - 'year YEAR' 'apply year YEAR' - - The space is optional. This sets a default year to be used for -subsequent dates which don't specify a year. Eg: - -Y2009 ; set default year to 2009 - -12/15 ; equivalent to 2009/12/15 - expenses 1 - assets - -year 2010 ; change default year to 2010 - -2009/1/30 ; specifies the year, not affected - expenses 1 - assets - -1/31 ; equivalent to 2010/1/31 - expenses 1 - assets - - Downsides: omitting the year (from primary transaction dates, at -least) makes your financial data less explicit, less portable, and less -trustworthy in an audit. Such dates can get separated from their -corresponding Y directive, eg when evaluating a region of the journal in -your editor. A missing Y directive makes reports dependent on today's -date. - - -File: hledger.info, Node: Secondary dates, Next: Star comments, Prev: Y directive, Up: Other syntax - -8.27.6 Secondary dates ----------------------- - -A secondary date is written after the primary date, following an equals -sign: 'DATE1=DATE2'. If the year is omitted, the primary date's year is -assumed. When running reports, the primary (left side) date is used by -default, but with the '--date2' flag ('--aux-date' or'--effective' also -work, for Ledger users), the secondary (right side) date will be used -instead. - - The meaning of secondary dates is up to you. Eg it could be "primary -is the bank's clearing date, secondary is the date the transaction was -initiated, if different". - - In practice, this feature usually adds confusion: - - * You have to remember the primary and secondary dates' meaning, and - follow that consistently. - * It splits your bookkeeping into two modes, and you have to remember - which mode is appropriate for a given report. - * Usually your balance assertions will work with only one of these - modes. - * It makes your financial data more complicated, less portable, and - less clear in an audit. - * It interacts with every feature, creating an ongoing cost for - implementors. - * It distracts new users and supporters. - * Posting dates are simpler and work better. - - So secondary dates are officially deprecated in hledger, remaining -only as a Ledger compatibility aid; we recommend using posting dates -instead. - - -File: hledger.info, Node: Star comments, Next: Valuation expressions, Prev: Secondary dates, Up: Other syntax - -8.27.7 Star comments --------------------- - -Lines beginning with '*' (star/asterisk) are also comment lines. This -feature allows Emacs users to insert org headings in their journal, -allowing them to fold/unfold/navigate it like an outline when viewed -with org mode. - - Downsides: another, unconventional comment syntax to learn. -Decreases your journal's portability. And switching to Emacs org mode -just for folding/unfolding meant losing the benefits of ledger mode; -nowadays you can add outshine mode to ledger mode to get folding without -losing ledger mode's features. - - -File: hledger.info, Node: Valuation expressions, Next: Virtual postings, Prev: Star comments, Up: Other syntax - -8.27.8 Valuation expressions ----------------------------- - -Ledger allows a valuation function or value to be written in double -parentheses after an amount. hledger ignores these. - - -File: hledger.info, Node: Virtual postings, Next: Other Ledger directives, Prev: Valuation expressions, Up: Other syntax - -8.27.9 Virtual postings ------------------------ - -A posting with parentheses around the account name, like '(some:account) -10', is called an _unbalanced virtual posting_. These postings do not -participate in transaction balancing. (And if you write them without an -amount, a zero amount is always inferred.) These can occasionally be -convenient for special circumstances, but they violate double entry -bookkeeping and make your data less portable across applications, so -many people avoid using them at all. - - A posting with brackets around the account name ('[some:account]') is -called a _balanced virtual posting_. The balanced virtual postings in a -transaction must add up to zero, just like ordinary postings, but -separately from them. These are not part of double entry bookkeeping -either, but they are at least balanced. An example: - -2022-01-01 buy food with cash, update budget envelope subaccounts, & something else - assets:cash $-10 ; <- these balance each other - expenses:food $7 ; <- - expenses:food $3 ; <- - [assets:checking:budget:food] $-10 ; <- and these balance each other - [assets:checking:available] $10 ; <- - (something:else) $5 ; <- this is not required to balance - - Ordinary postings, whose account names are neither parenthesised nor -bracketed, are called _real postings_. You can exclude virtual postings -from reports with the '-R/--real' flag or a 'real:1' query. - - -File: hledger.info, Node: Other Ledger directives, Next: Other cost/lot notations, Prev: Virtual postings, Up: Other syntax - -8.27.10 Other Ledger directives -------------------------------- - -These other Ledger directives are currently accepted but ignored. This -allows hledger to read more Ledger files, but be aware that hledger's -reports may differ from Ledger's if you use these. - -apply fixed COMM AMT -apply tag TAG -assert EXPR -bucket / A ACCT -capture ACCT REGEX -check EXPR -define VAR=EXPR -end apply fixed -end apply tag -end apply year -end tag -eval / expr EXPR -python - PYTHONCODE -tag NAME -value EXPR ---command-line-flags - - See also https://hledger.org/ledger.html for a detailed -hledger/Ledger syntax comparison. - - -File: hledger.info, Node: Other cost/lot notations, Prev: Other Ledger directives, Up: Other syntax - -8.27.11 Other cost/lot notations --------------------------------- - -A slight digression for Ledger and Beancount users. - - *Ledger* has a number of cost/lot-related notations: - - * '@ UNITCOST' and '@@ TOTALCOST' - * expresses a conversion rate, as in hledger - * when buying, also creates a lot that can be selected at - selling time - - * '(@) UNITCOST' and '(@@) TOTALCOST' (virtual cost) - * like the above, but also means "this cost was exceptional, - don't use it when inferring market prices". - - * '{=UNITCOST}' and '{{=TOTALCOST}}' (fixed price) - * when buying, means "this cost is also the fixed value, don't - let it fluctuate in value reports" - - * '{UNITCOST}' and '{{TOTALCOST}}' (lot price) - * can be used identically to '@ UNITCOST' and '@@ TOTALCOST', - also creates a lot - * when selling, combined with '@ ...', selects an existing lot - by its cost basis. Does not check if that lot is present. - - * '[YYYY/MM/DD]' (lot date) - * when buying, attaches this acquisition date to the lot - * when selling, selects a lot by its acquisition date - - * '(SOME TEXT)' (lot note) - * when buying, attaches this note to the lot - * when selling, selects a lot by its note - - Currently, hledger - - * accepts any or all of the above in any order after the posting - amount - * supports '@' and '@@' - * treats '(@)' and '(@@)' as synonyms for '@' and '@@' - * and ignores the rest. (This can break transaction balancing.) - - *Beancount* has simpler notation and different behaviour: - - * '@ UNITCOST' and '@@ TOTALCOST' - * expresses a cost without creating a lot, as in hledger - * when buying (acquiring) or selling (disposing of) a lot, and - combined with '{...}': is not used except to document the - cost/selling price - - * '{UNITCOST}' and '{{TOTALCOST}}' - * when buying, expresses the cost for transaction balancing, and - also creates a lot with this cost basis attached - * when selling, - * selects a lot by its cost basis - * raises an error if that lot is not present or can not be - selected unambiguously (depending on booking method - configured) - * expresses the selling price for transaction balancing - - * '{}', '{YYYY-MM-DD}', '{"LABEL"}', '{UNITCOST, "LABEL"}', - '{UNITCOST, YYYY-MM-DD, "LABEL"}' - * when selling, other combinations of date/cost/label, like the - above, are accepted for selecting the lot. - - Currently, hledger - - * supports '@' and '@@' - * accepts the '{UNITCOST}'/'{{TOTALCOST}}' notation, but ignores it - * and rejects the rest. - - -File: hledger.info, Node: CSV, Next: Timeclock, Prev: Journal, Up: Top - -9 CSV -***** - -hledger can read transactions from CSV (comma-separated values) files. -More precisely, it can read DSV (delimiter-separated values), from a -file or standard input. Comma-separated, semicolon-separated and -tab-separated are the most common variants, and hledger will recognise -these three automatically based on a '.csv', '.ssv' or '.tsv' file name -extension or a 'csv:', 'ssv:' or 'tsv:' file path prefix. - - (To learn about producing CSV or TSV _output_, see Output format.) - - Each CSV file must be described by a corresponding _rules file_. -This contains rules describing the CSV data (header line, fields layout, -date format etc.), how to construct hledger transactions from it, and -how to categorise transactions based on description or other attributes. - - By default, hledger expects this rules file to be named like the CSV -file, with an extra '.rules' extension added, in the same directory. Eg -when asked to read 'foo/FILE.csv', hledger looks for -'foo/FILE.csv.rules'. You can specify a different rules file with the -'--rules' option. - - At minimum, the rules file must identify the date and amount fields, -and often it also specifies the date format and how many header lines -there are. Here's a simple CSV file and a rules file for it: - -Date, Description, Id, Amount -12/11/2019, Foo, 123, 10.23 - -# basic.csv.rules -skip 1 -fields date, description, , amount -date-format %d/%m/%Y - -$ hledger print -f basic.csv -2019-11-12 Foo - expenses:unknown 10.23 - income:unknown -10.23 - - There's an introductory Tutorial: Import CSV data 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:: -* archive:: -* encoding:: -* separator:: -* skip:: -* date-format:: -* timezone:: -* newest-first:: -* intra-day-reversed:: -* decimal-mark:: -* fields list:: -* Field assignment:: -* Field names:: -* if block:: -* Matchers:: -* if table:: -* balance-type:: -* include:: -* Working with CSV:: -* CSV rules examples:: - - -File: hledger.info, Node: CSV rules cheatsheet, Next: source, Up: CSV - -9.1 CSV rules cheatsheet -======================== - -The following kinds of rule can appear in the rules file, in any order. -(Blank lines and lines beginning with '#' or ';' or '*' are ignored.) - -*'source'* optionally declare which file to read data - from -*'archive'* optionally enable an archive of imported files -*'encoding'* optionally declare which text encoding the - data has -*'separator'* declare the field separator, instead of - relying on file extension -*'skip'* skip one or more header lines at start of file -*'date-format'* declare how to parse CSV dates/date-times -*'timezone'* declare the time zone of ambiguous CSV - date-times -*'newest-first'* improve txn order when: there are multiple - records, newest first, all with the same date -*'intra-day-reversed'* improve txn order when: same-day txns are in - opposite order to the overall file -*'decimal-mark'* declare the decimal mark used in CSV amounts, - when ambiguous -*'fields' list* name CSV fields for easy reference, and - optionally assign their values to hledger - fields -*Field assignment* assign a CSV value or interpolated text value - to a hledger field -*'if' block* conditionally assign values to hledger fields, - or 'skip' a record or 'end' (skip rest of - file) -*'if' table* conditionally assign values to hledger fields, - using compact syntax -*'balance-type'* select which type of balance - assertions/assignments to generate -*'include'* inline another CSV rules file - - Working with CSV tips can be found below, including How CSV rules are -evaluated. - - -File: hledger.info, Node: source, Next: archive, Prev: CSV rules cheatsheet, Up: CSV - -9.2 'source' -============ - -If you tell hledger to read a csv file with '-f foo.csv', it will look -for rules in 'foo.csv.rules'. Or, you can tell it to read the rules -file, with '-f foo.csv.rules', and it will look for data in 'foo.csv' -(since 1.30). These are mostly equivalent, but the second method -provides some extra features. For one, the data file can be missing, -without causing an error; it is just considered empty. - - For more flexibility, add a 'source' rule, which lets you specify a -different data file: - -source ./Checking1.csv - - If the file does not exist, it is just considered empty, without -raising an error. - - If you specify just a file name with no path, hledger will look for -it in the '~/Downloads' folder: - -source Checking1.csv - - You can use a glob pattern, to avoid specifying the file name -exactly: - -source Checking1*.csv - - This has another benefit: if the pattern matches multiple files, -hledger will read the newest (most recently modified) one. This avoids -problems if you have downloaded a file multiple times without cleaning -up. - - All this enables a convenient workflow where can you just download -CSV files, then run 'hledger import rules/*'. - - See also "Working with CSV > Reading files specified by rule". - -* Menu: - -* Data cleaning / generating commands:: - - -File: hledger.info, Node: Data cleaning / generating commands, Up: source - -9.2.1 Data cleaning / generating commands ------------------------------------------ - -After 'source''s file pattern, you can write '|' (pipe) and a data -cleaning command. If hledger's CSV rules aren't enough, you can -pre-process the downloaded data here with a shell command or script, to -make it more suitable for conversion. The command will be executed by -your default shell, in the directory of the rules file, will receive the -data file's content as standard input, and should output zero or more -lines of character-separated-values, suitable for conversion by the CSV -rules. - - Examples: - -source ./paypal.json | paypalcsv -source data/simplefin.json | simplefincsv - 'chase.*card' -source OfxDownload*.csv | grep -vE '^(([^,]*,){6}[^,]*|)$' | sort -t, -n +2 -source History_for_Account_Z20144832*.csv # | grep -E '^([^,]*,){12}[^,]*$' | sed -E -e 's/^ //' -e 's/\.([0-9]),/.\10,/g' -e 's/,([0-9]+),/,\1.00,/g' - - Or, after 'source' you can write '|' and a data generating command -(with no file pattern before the '|'). This command receives no input, -and should output zero or more lines of character-separated values, -suitable for conversion by the CSV rules. - - Examples: - -source | paypaljson | paypalcsv -source | paypalcsv data/paypal.json -source | simplefinjson >data/simplefin.json && simplefincsv data/simplefin.json 'chase.*card' -source | simplefincsv data/simplefin.json 'unify.*checking' - - ('paypal*' and 'simplefin*' scripts are in bin/) - - Whenever hledger runs one of these commands, it will echo the command -on stderr. If the command produces error output, but exits -successfully, hledger will show the error output as a warning. If the -command fails, hledger will fail and show the error output in the error -message. - - _Added in 1.50; experimental._ - - -File: hledger.info, Node: archive, Next: encoding, Prev: source, Up: CSV - -9.3 'archive' -============= - -With 'archive' added to a rules file, the 'import' command will archive -each successfully processed data file or data command output in a nearby -'data/' directory. The archive file name will be based on the rules -file and the data file's modification date and extension (or for a -data-generating command, the current date and the ".csv" extension). -The original data file, if any, will be removed. - - Also, in this mode 'import' will prefer the oldest file matched by -the 'source' rule's glob pattern, not the newest. (So if there are -multiple downloads, they will be imported and archived oldest first.) - - Archiving is optional, but it can be useful for troubleshooting your -CSV rules, regenerating entries with improved rules, checking for -variations in your bank's CSV, etc. - - _Added in 1.50; experimental._ - - -File: hledger.info, Node: encoding, Next: separator, Prev: archive, Up: CSV - -9.4 'encoding' -============== - -encoding ENCODING - - hledger normally expects non-ascii text to be using the system -locale's text encoding. If you need to read CSV files which have some -other encoding, you can do it by adding 'encoding ENCODING' to your CSV -rules. Eg: 'encoding iso-8859-1'. - - The following encodings are supported: - - 'ascii', 'utf-8', 'utf-16', 'utf-32', 'iso-8859-1', 'iso-8859-2', -'iso-8859-3', 'iso-8859-4', 'iso-8859-5', 'iso-8859-6', 'iso-8859-7', -'iso-8859-8', 'iso-8859-9', 'iso-8859-10', 'iso-8859-11', 'iso-8859-13', -'iso-8859-14', 'iso-8859-15', 'iso-8859-16', 'cp1250', 'cp1251', -'cp1252', 'cp1253', 'cp1254', 'cp1255', 'cp1256', 'cp1257', 'cp1258', -'koi8-r', 'koi8-u', 'gb18030', 'macintosh', 'jis-x-0201', 'jis-x-0208', -'iso-2022-jp', 'shift-jis', 'cp437', 'cp737', 'cp775', 'cp850', 'cp852', -'cp855', 'cp857', 'cp860', 'cp861', 'cp862', 'cp863', 'cp864', 'cp865', -'cp866', 'cp869', 'cp874', 'cp932'. - - _Added in 1.42._ - - -File: hledger.info, Node: separator, Next: skip, Prev: encoding, Up: CSV - -9.5 'separator' -=============== - -You can use the 'separator' rule to read other kinds of -character-separated data. The argument is any single separator -character, or the words 'tab' or 'space' (case insensitive). Eg, for -comma-separated values (CSV): - -separator , - - or for semicolon-separated values (SSV): - -separator ; - - or for tab-separated values (TSV): - -separator TAB - - If the input file has a '.csv', '.ssv' or '.tsv' file extension (or a -'csv:', 'ssv:', 'tsv:' prefix), the appropriate separator will be -inferred automatically, and you won't need this rule. - - -File: hledger.info, Node: skip, Next: date-format, Prev: separator, Up: CSV - -9.6 'skip' -========== - -skip N - - The word 'skip' followed by a number (or no number, meaning 1) tells -hledger to ignore this many non-empty lines at the start of the input -data. You'll need this whenever your CSV data contains header lines. -Note, empty and blank lines are skipped automatically, so you don't need -to count those. - - 'skip' has a second meaning: it can be used inside if blocks -(described below), to skip one or more records whenever the condition is -true. Records skipped in this way are ignored, except they are still -required to be valid CSV. - - -File: hledger.info, Node: date-format, Next: timezone, Prev: skip, Up: CSV - -9.7 '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 - - Note currently there is no locale awareness for things like '%b', and -setting LC_TIME won't help. - - -File: hledger.info, Node: timezone, Next: newest-first, Prev: date-format, Up: CSV - -9.8 'timezone' -============== - -timezone TIMEZONE - - When CSV contains date-times that are implicitly in some time zone -other than yours, but containing no explicit time zone information, you -can use this rule to declare the CSV's native time zone, which helps -prevent off-by-one dates. - - When the CSV date-times do contain time zone information, you don't -need this rule; instead, use '%Z' in 'date-format' (or '%z', '%EZ', -'%Ez'; see the formatTime link above). - - In either of these cases, hledger will do a time-zone-aware -conversion, localising the CSV date-times to your current system time -zone. If you prefer to localise to some other time zone, eg for -reproducibility, you can (on unix at least) set the output timezone with -the TZ environment variable, eg: - -$ TZ=-1000 hledger print -f foo.csv # or TZ=-1000 hledger import foo.csv - - 'timezone' currently does not understand timezone names, except -"UTC", "GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT". -For others, use numeric format: +HHMM or -HHMM. - - -File: hledger.info, Node: newest-first, Next: intra-day-reversed, Prev: timezone, Up: CSV - -9.9 'newest-first' -================== - -hledger tries to ensure that the generated transactions will be ordered -chronologically, including same-day transactions. Usually it can -auto-detect how the CSV records are ordered. But if it encounters CSV -where all records are on the same date, it assumes that the records are -oldest first. If in fact the CSV's records are normally newest first, -like: - -2022-10-01, txn 3... -2022-10-01, txn 2... -2022-10-01, txn 1... - - you can add the 'newest-first' rule to help hledger generate the -transactions in correct order. - -# same-day CSV records are newest first -newest-first - - -File: hledger.info, Node: intra-day-reversed, Next: decimal-mark, Prev: newest-first, Up: CSV - -9.10 'intra-day-reversed' -========================= - -If CSV records within a single day are ordered opposite to the overall -record order, you can add the 'intra-day-reversed' rule to improve the -order of journal entries. Eg, here the overall record order is newest -first, but same-day records are oldest first: - -2022-10-02, txn 3... -2022-10-02, txn 4... -2022-10-01, txn 1... -2022-10-01, txn 2... - -# transactions within each day are reversed with respect to the overall date order -intra-day-reversed - - -File: hledger.info, Node: decimal-mark, Next: fields list, Prev: intra-day-reversed, Up: CSV - -9.11 'decimal-mark' -=================== - -decimal-mark . - - or: - -decimal-mark , - - hledger automatically accepts either period or comma as a decimal -mark when parsing numbers (cf Amounts). However if any numbers in the -CSV contain digit group marks, such as thousand-separating commas, you -should declare the decimal mark explicitly with this rule, to avoid -misparsed numbers. - - -File: hledger.info, Node: fields list, Next: Field assignment, Prev: decimal-mark, Up: CSV - -9.12 'fields' list -================== - -fields FIELDNAME1, FIELDNAME2, ... - - A fields list (the word 'fields' followed by comma-separated field -names) is optional, but convenient. It does two things: - - 1. It names the CSV field in each column. This can be convenient if - you are referencing them in other rules, so you can say - '%SomeField' instead of remembering '%13'. - - 2. Whenever you use one of the special hledger field names (described - below), it assigns the CSV value in this position to that hledger - field. This is the quickest way to populate hledger's fields and - build a transaction. - - Here's an example that says "use the 1st, 2nd and 4th fields as the -transaction's date, description and amount; name the last two fields for -later reference; and ignore the others": - -fields date, description, , amount, , , somefield, anotherfield - - In a fields list, the separator is always comma; it is unrelated to -the CSV file's separator. Also: - - * There must be least two items in the list (at least one comma). - * Field names may not contain spaces. Spaces before/after field - names are optional. - * Field names may contain '_' (underscore) or '-' (hyphen). - * Fields you don't care about can be given a dummy name or an empty - name. - - If the CSV contains column headings, it's convenient to use these for -your field names, suitably modified (eg lower-cased with spaces replaced -by underscores). - - Sometimes you may want to alter a CSV field name to avoid assigning -to a hledger field with the same name. Eg you could call the CSV's -"balance" field 'balance_' to avoid directly setting hledger's 'balance' -field (and generating a balance assertion). - - -File: hledger.info, Node: Field assignment, Next: Field names, Prev: fields list, Up: CSV - -9.13 Field assignment -===================== - -HLEDGERFIELD FIELDVALUE - - Field assignments are the more flexible way to assign CSV values to -hledger fields. They can be used instead of or in addition to a fields -list (see above). - - To assign a value to a hledger field, write the field name (any of -the standard hledger field/pseudo-field names, defined below), a space, -followed by a text value on the same line. This text value may -interpolate CSV fields, referenced either by their 1-based position in -the CSV record ('%N') or by the name they were given in the fields list -('%CSVFIELD'), and regular expression match groups ('\N'). - - Some examples: - -# set the amount to the 4th CSV field, with " USD" appended -amount %4 USD - -# combine three fields to make a comment, containing note: and date: tags -comment note: %somefield - %anotherfield, date: %1 - - Tips: - - * Interpolation strips outer whitespace (so a CSV value like '" 1 "' - becomes '1' when interpolated) (#1051). - * Interpolations always refer to a CSV field - you can't interpolate - a hledger field. (See Referencing other fields below). - - -File: hledger.info, Node: Field names, Next: if block, Prev: Field assignment, Up: CSV - -9.14 Field names -================ - -Note the two kinds of field names mentioned here, and used only in -hledger CSV rules files: - - 1. *CSV field names* ('CSVFIELD' in these docs): you can optionally - name the CSV columns for easy reference (since hledger doesn't yet - automatically recognise column headings in a CSV file), by writing - arbitrary names in a 'fields' list, eg: - - fields When, What, Some_Id, Net, Total, Foo, Bar - - 2. Special *hledger field names* ('HLEDGERFIELD' in these docs): you - must set at least some of these to generate the hledger transaction - from a CSV record, by writing them as the left hand side of a field - assignment, eg: - - date %When - code %Some_Id - description %What - comment %Foo %Bar - amount1 $ %Total - - or directly in a 'fields' list: - - fields date, description, code, , amount1, Foo, Bar - currency $ - comment %Foo %Bar - - Here are all the special hledger field names available, and what -happens when you assign values to them: - -* Menu: - -* date field:: -* date2 field:: -* status field:: -* code field:: -* description field:: -* comment field:: -* account field:: -* amount field:: -* currency field:: -* balance field:: - - -File: hledger.info, Node: date field, Next: date2 field, Up: Field names - -9.14.1 date field ------------------ - -Assigning to 'date' sets the transaction date. - - -File: hledger.info, Node: date2 field, Next: status field, Prev: date field, Up: Field names - -9.14.2 date2 field ------------------- - -'date2' sets the transaction's secondary date, if any. - - -File: hledger.info, Node: status field, Next: code field, Prev: date2 field, Up: Field names - -9.14.3 status field -------------------- - -'status' sets the transaction's status, if any. - - -File: hledger.info, Node: code field, Next: description field, Prev: status field, Up: Field names - -9.14.4 code field ------------------ - -'code' sets the transaction's code, if any. - - -File: hledger.info, Node: description field, Next: comment field, Prev: code field, Up: Field names - -9.14.5 description field ------------------------- - -'description' sets the transaction's description, if any. - - -File: hledger.info, Node: comment field, Next: account field, Prev: description field, Up: Field names - -9.14.6 comment field --------------------- - -'comment' sets the transaction's comment, if any. - - 'commentN', where N is a number, sets the Nth posting's comment. - - You can assign multi-line comments by writing literal '\n' in the -code. A comment starting with '\n' will begin on a new line. - - Comments can contain tags, as usual. - - Posting comments can also contain a posting date. A secondary date, -or a year-less date, will be ignored. - - -File: hledger.info, Node: account field, Next: amount field, Prev: comment field, Up: Field names - -9.14.7 account field --------------------- - -Assigning to 'accountN', where N is 1 to 99, sets the account name of -the Nth posting, and causes that posting to be generated. - - Most often there are two postings, so you'll want to set 'account1' -and 'account2'. Typically 'account1' is associated with the CSV file, -and is set once with a top-level assignment, while 'account2' is set -based on each transaction's description, in conditional rules. - - If a posting's account name is left unset but its amount is set (see -below), a default account name will be chosen (like "expenses:unknown" -or "income:unknown"). - - -File: hledger.info, Node: amount field, Next: currency field, Prev: account field, Up: Field names - -9.14.8 amount field -------------------- - -There are several ways to set posting amounts from CSV, useful in -different situations. - - 1. *'amount'* is the oldest and simplest. Assigning to this sets the - amount of the first and second postings. In the second posting, - the amount will be negated; also, if it has a cost attached, it - will be converted to cost. - - 2. *'amount-in'* and *'amount-out'* work exactly like the above, but - should be used when the CSV has two amount fields (such as "Debit" - and "Credit", or "Inflow" and "Outflow"). Whichever field has a - non-zero value will be used as the amount of the first and second - postings. Here are some tips to avoid confusion: - - * It's not "amount-in for posting 1 and amount-out for posting - 2", it is "extract a single amount from the amount-in or - amount-out field, and use that for posting 1 and (negated) for - posting 2". - * Don't use both 'amount' and 'amount-in'/'amount-out' in the - same rules file; choose based on whether the amount is in a - single CSV field or spread across two fields. - * In each record, at most one of the two CSV fields should - contain a non-zero amount; the other field must contain a zero - or nothing. - * hledger assumes both CSV fields contain unsigned numbers, and - it automatically negates the amount-out values. - * If the data doesn't fit these requirements, you'll probably - need an if rule (see below). - - 3. *'amountN'* (where N is a number from 1 to 99) sets the amount of - only a single posting: the Nth posting in the transaction. You'll - usually need at least two such assignments to make a balanced - transaction. You can also generate more than two postings, to - represent more complex transactions. The posting numbers don't - have to be consecutive; with if rules, higher posting numbers can - be useful to ensure a certain order of postings. - - 4. *'amountN-in'* and *'amountN-out'* work exactly like the above, but - should be used when the CSV has two amount fields. This is - analogous to 'amount-in' and 'amount-out', and those tips also - apply here. - - 5. Remember that a 'fields' list can also do assignments. So in a - fields list if you name a CSV field "amount", that counts as - assigning to 'amount'. (If you don't want that, call it something - else in the fields list, like "amount_".) - - 6. The above don't handle every situation; if you need more - flexibility, use an 'if' rule to set amounts conditionally. See - "Working with CSV > Setting amounts" below for more on this and on - amount-setting generally. - - -File: hledger.info, Node: currency field, Next: balance field, Prev: amount field, Up: Field names - -9.14.9 currency field ---------------------- - -'currency' sets a currency symbol, to be prepended to all postings' -amounts. You can use this if the CSV amounts do not have a currency -symbol, eg if it is in a separate column. - - 'currencyN' prepends a currency symbol to just the Nth posting's -amount. - - -File: hledger.info, Node: balance field, Prev: currency field, Up: Field names - -9.14.10 balance field ---------------------- - -'balanceN' sets a balance assertion amount (or if the posting amount is -left empty, a balance assignment) on posting N. - - 'balance' is a compatibility spelling for hledger <1.17; it is -equivalent to 'balance1'. - - You can adjust the type of assertion/assignment with the -'balance-type' rule (see below). - - See the Working with CSV tips below for more about setting amounts -and currency. - - -File: hledger.info, Node: if block, Next: Matchers, Prev: Field names, Up: CSV - -9.15 'if' block -=============== - -Rules can be applied conditionally, depending on patterns in the CSV -data. This allows flexibility; in particular, it is how you can -categorise transactions, selecting an appropriate account name based on -their description (for example). There are two ways to write -conditional rules: "if blocks", described here, and "if tables", -described below. - - An if block is the word 'if' and one or more "matcher" expressions -(can be a word or phrase), one per line, starting either on the same or -next line; followed by one or more indented rules. Eg, - -if MATCHER - RULE - - or - -if -MATCHER -MATCHER -MATCHER - RULE - RULE - - If any of the matchers succeeds, all of the indented rules will be -applied. They are usually field assignments, but the following special -rules may also be used within an if block: - - * 'skip' - skips the matched CSV record (generating no transaction - from it) - * 'end' - skips the rest of the current CSV file. - - Some examples: - -# if the record contains "groceries", set account2 to "expenses:groceries" -if groceries - account2 expenses:groceries - -# if the record contains any of these phrases, set account2 and a transaction comment as shown -if -monthly service fee -atm transaction fee -banking thru software - account2 expenses:business:banking - comment XXX deductible ? check it - -# if an empty record is seen (assuming five fields), ignore the rest of the CSV file -if ,,,, - end - - -File: hledger.info, Node: Matchers, Next: if table, Prev: if block, Up: CSV - -9.16 Matchers -============= - -There are two kinds of matcher: - - 1. A whole record matcher is simplest: it is just a word, single-line - text fragment, or other regular expression, which hledger will try - to match case-insensitively anywhere within the CSV record. - Eg: 'whole foods'. - - 2. A field matcher has a percent-prefixed CSV field number or name - before the pattern. - Eg: '%3 whole foods' or '%description whole foods'. - hledger will try to match the pattern just within the named CSV - field. - - When using these, there's two things to be aware of: - - 1. Whole record matchers don't see the exact original record; they see - a reconstruction of it, in which values are comma-separated, and - quotes enclosing values and whitespace outside those quotes are - removed. - Eg when reading an SSV record like: '2023-01-01 ; "Acme, Inc. " ; - 1,000' - the whole record matcher sees instead: '2023-01-01,Acme, Inc. - ,1,000' - - 2. Field matchers expect either a CSV field number, or a CSV field - name declared with 'fields'. (Don't use a hledger field name here, - unless it is also a CSV field name.) A non-CSV field name will - cause the matcher to match against '""' (the empty string), and - does not raise an error, allowing easier reuse of common rules with - different CSV files. - - You can also prefix a matcher with '!' (and optional space) to negate -it. Eg '! whole foods', '! %3 whole foods', '!%description whole foods' -will match if "whole foods" is NOT present. _Added in 1.32._ - - The pattern is, as usual in hledger, a POSIX extended regular -expression that also supports GNU word boundaries ('\b', '\B', '\<', -'\>') and nothing else. If you have trouble with it, see "Regular -expressions" in the hledger manual -(https://hledger.org/hledger.html#regular-expressions). - -* Menu: - -* Multiple matchers:: -* Match groups:: - - -File: hledger.info, Node: Multiple matchers, Next: Match groups, Up: Matchers - -9.16.1 Multiple matchers ------------------------- - -When an if block has multiple matchers, each on its own line, - - * By default they are OR'd (any of them can match). - * Matcher lines beginning with '&' (or '&&', _since 1.42_) are AND'ed - with the matcher above (all in the AND'ed group must match). - * Matcher lines beginning with '& !' (_since 1.41_, or '&& !', _since - 1.42_) are first negated and then AND'ed with the matcher above. - - You can also combine multiple matchers one the same line separated by -'&&' (AND) or '&& !' (AND NOT). Eg '%description amazon && %date -2025-01-01' will match only when the description field contains "amazon" -and the date field contains "2025-01-01". _Added in 1.42._ - - -File: hledger.info, Node: Match groups, Prev: Multiple matchers, Up: Matchers - -9.16.2 Match groups -------------------- - -_Added in 1.32_ - - Matchers can define match groups: parenthesised portions of the -regular expression which are available for reference in field -assignments. Groups are enclosed in regular parentheses ('(' and ')') -and can be nested. Each group is available in field assignments using -the token '\N', where N is an index into the match groups for this -conditional block (e.g. '\1', '\2', etc.). - - Example: Warp credit card payment postings to the beginning of the -billing period (Month start), to match how they are presented in -statements, using posting dates: - -if %date (....-..)-.. - comment2 date:\1-01 - - Another example: Read the expense account from the CSV field, but -throw away a prefix: - -if %account1 liabilities:family:(expenses:.*) - account1 \1 - - -File: hledger.info, Node: if table, Next: balance-type, Prev: Matchers, Up: CSV - -9.17 'if' table -=============== - -"if tables" are an alternative to if blocks; they can express many -matchers and field assignments in a more compact tabular format, like -this: - -if,HLEDGERFIELD1,HLEDGERFIELD2,... -MATCHERA,VALUE1,VALUE2,... -MATCHERB && MATCHERC,VALUE1,VALUE2,... (*since 1.42*) -; Comment line that explains MATCHERD -MATCHERD,VALUE1,VALUE2,... - - - The first character after 'if' is taken to be this if table's field -separator. It is unrelated to the separator used in the CSV file. It -should be a non-alphanumeric character like ',' or '|' that does not -appear anywhere else in the table (it should not be used in field names -or matchers or values, and it cannot be escaped with a backslash). - - Each line must contain the same number of separators; empty values -are allowed. Whitespace can be used in the matcher lines for -readability (but not in the if line, currently). You can use the -comment lines in the table body. The table must be terminated by an -empty line (or end of file). - - An if table like the above is interpreted as follows: try all of the -lines with matchers; whenever a line with matchers succeeds, assign all -of the values on that line to the corresponding hledger fields; If -multiple lines match, later lines will override fields assigned by the -earlier ones - just like the sequence of 'if' blocks would behave. - - If table presented above is equivalent to this sequence of if blocks: - -if MATCHERA - HLEDGERFIELD1 VALUE1 - HLEDGERFIELD2 VALUE2 - ... - -if MATCHERB && MATCHERC - HLEDGERFIELD1 VALUE1 - HLEDGERFIELD2 VALUE2 - ... - -; Comment line which explains MATCHERD -if MATCHERD - HLEDGERFIELD1 VALUE1 - HLEDGERFIELD2 VALUE2 - ... - - Example: - -if,account2,comment -atm transaction fee,expenses:business:banking,deductible? check it -%description groceries,expenses:groceries, -;; Comment line that desribes why this particular date is special -2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out - - -File: hledger.info, Node: balance-type, Next: include, Prev: if table, Up: CSV - -9.18 'balance-type' -=================== - -Balance assertions generated by assigning to balanceN are of the simple -'=' type by default, which is a single-commodity, subaccount-excluding -assertion. You may find the subaccount-including variants more useful, -eg if you have created some virtual subaccounts of checking to help with -budgeting. You can select a different type of assertion with the -'balance-type' rule: - -# balance assertions will consider all commodities and all subaccounts -balance-type ==* - - Here are the balance assertion types for quick reference: - -= single commodity, exclude subaccounts -=* single commodity, include subaccounts -== multi commodity, exclude subaccounts -==* multi commodity, include subaccounts - - -File: hledger.info, Node: include, Next: Working with CSV, Prev: balance-type, Up: CSV - -9.19 'include' -============== - -include RULESFILE - - This includes the contents of another CSV rules file at this point. -'RULESFILE' is an absolute file path or a path relative to the current -file's directory. This can be useful for sharing common rules between -several rules files, eg: - -# someaccount.csv.rules - -## someaccount-specific rules -fields date,description,amount -account1 assets:someaccount -account2 expenses:misc - -## common rules -include categorisation.rules - - -File: hledger.info, Node: Working with CSV, Next: CSV rules examples, Prev: include, Up: CSV - -9.20 Working with CSV -===================== - -Some tips: - -* Menu: - -* Rapid feedback:: -* Valid CSV:: -* File Extension:: -* Reading CSV from standard input:: -* Reading multiple CSV files:: -* Reading files specified by rule:: -* Valid transactions:: -* Deduplicating importing:: -* Setting amounts:: -* Amount signs:: -* Setting currency/commodity:: -* Amount decimal places:: -* Referencing other fields:: -* How CSV rules are evaluated:: -* Well factored rules:: - - -File: hledger.info, Node: Rapid feedback, Next: Valid CSV, Up: Working with CSV - -9.20.1 Rapid feedback ---------------------- - -It's a good idea to get rapid feedback while creating/troubleshooting -CSV rules. Here's a good way, using entr from eradman.com/entrproject: - -$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC' - - A desc: query (eg) is used to select just one, or a few, transactions -of interest. "bash -c" is used to run multiple commands, so we can echo -a separator each time the command re-runs, making it easier to read the -output. - - -File: hledger.info, Node: Valid CSV, Next: File Extension, Prev: Rapid feedback, Up: Working with CSV - -9.20.2 Valid CSV ----------------- - -Note that hledger will only accept valid CSV conforming to RFC 4180, and -equivalent SSV and TSV formats (like RFC 4180 but with semicolon or tab -as separators). This means, eg: - - * Values may be enclosed in double quotes, or not. Enclosing in - single quotes is not allowed. (Eg ''A','B'' is rejected.) - * When values are enclosed in double quotes, spaces outside the - quotes are not allowed. (Eg '"A", "B"' is rejected.) - * When values are not enclosed in quotes, they may not contain double - quotes. (Eg 'A"A, B' is rejected.) - - If your CSV/SSV/TSV is not valid in this sense, you'll need to -transform it before reading with hledger. Try using sed, or a more -permissive CSV parser like python's csv lib. - - -File: hledger.info, Node: File Extension, Next: Reading CSV from standard input, Prev: Valid CSV, Up: Working with CSV - -9.20.3 File Extension ---------------------- - -To help hledger choose the CSV file reader and show the right error -messages (and choose the right field separator character by default), -it's best if CSV/SSV/TSV files are named with a '.csv', '.ssv' or '.tsv' -filename extension. (More about this at Data formats.) - - When reading files with the "wrong" extension, you can ensure the CSV -reader (and the default field separator) by prefixing the file path with -'csv:', 'ssv:' or 'tsv:': Eg: - -$ hledger -f ssv:foo.dat print - - You can also override the default field separator with a separator -rule if needed. - - -File: hledger.info, Node: Reading CSV from standard input, Next: Reading multiple CSV files, Prev: File Extension, Up: Working with CSV - -9.20.4 Reading CSV from standard input --------------------------------------- - -You'll need the file format prefix when reading CSV from stdin also, -since hledger assumes journal format by default. Eg: - -$ cat foo.dat | hledger -f ssv:- print - - -File: hledger.info, Node: Reading multiple CSV files, Next: Reading files specified by rule, Prev: Reading CSV from standard input, Up: Working with CSV - -9.20.5 Reading multiple CSV files ---------------------------------- - -If you use multiple '-f' options to read multiple CSV files at once, -hledger will look for a correspondingly-named rules file for each CSV -file. But if you specify a rules file with '--rules', that rules file -will be used for all the CSV files. - - -File: hledger.info, Node: Reading files specified by rule, Next: Valid transactions, Prev: Reading multiple CSV files, Up: Working with CSV - -9.20.6 Reading files specified by rule --------------------------------------- - -Instead of specifying a CSV file in the command line, you can specify a -rules file, as in 'hledger -f foo.csv.rules CMD'. By default this will -read data from foo.csv in the same directory, but you can add a source -rule to specify a different data file, perhaps located in your web -browser's download directory. - - This feature was added in hledger 1.30, so you won't see it in most -CSV rules examples. But it helps remove some of the busywork of -managing CSV downloads. Most of your financial institutions's default -CSV filenames are different and can be recognised by a glob pattern. So -you can put a rule like 'source Checking1*.csv' in -foo-checking.csv.rules, and then periodically follow a workflow like: - - 1. Download CSV from Foo's website, using your browser's defaults - 2. Run 'hledger import foo-checking.csv.rules' to import any new - transactions - - After import, you can: discard the CSV, or leave it where it is for a -while, or move it into your archives, as you prefer. If you do nothing, -next time your browser will save something like Checking1-2.csv, and -hledger will use that because of the '*' wild card and because it is the -most recent. - - -File: hledger.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading files specified by rule, Up: Working with CSV - -9.20.7 Valid transactions -------------------------- - -After reading a CSV file, hledger post-processes and validates the -generated journal entries as it would for a journal file - balancing -them, applying balance assignments, and canonicalising amount styles. -Any errors at this stage will be reported in the usual way, displaying -the problem entry. - - There is one exception: balance assertions, if you have generated -them, will not be checked, since normally these will work only when the -CSV data is part of the main journal. If you do need to check balance -assertions generated from CSV right away, pipe into another hledger: - -$ hledger -f file.csv print | hledger -f- print - - -File: hledger.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: Working with CSV - -9.20.8 Deduplicating, importing -------------------------------- - -When you download a CSV file periodically, eg to get your latest bank -transactions, the new file may overlap with the old one, containing some -of the same records. - - The import command will (a) detect the new transactions, and (b) -append just those transactions to your main journal. It is idempotent, -so you don't have to remember how many times you ran it or with which -version of the CSV. (It keeps state in a hidden '.latest.FILE.csv' -file.) This is the easiest way to import CSV data. Eg: - -# download the latest CSV files, then run this command. -# Note, no -f flags needed here. -$ hledger import *.csv [--dry] - - This method works for most CSV files. (Where records have a stable -chronological order, and new records appear only at the new end.) - - A number of other tools and workflows, hledger-specific and -otherwise, exist for converting, deduplicating, classifying and managing -CSV data. See: - - * https://hledger.org/cookbook.html#setups-and-workflows - * https://plaintextaccounting.org -> data import/conversion - - -File: hledger.info, Node: Setting amounts, Next: Amount signs, Prev: Deduplicating importing, Up: Working with CSV - -9.20.9 Setting amounts ----------------------- - -Continuing from amount field above, here are more tips for -amount-setting: - - 1. *If the amount is in a single CSV field:* - - a. *If its sign indicates direction of flow:* - Assign it to 'amountN', to set the Nth posting's amount. N is - usually 1 or 2 but can go up to 99. - - b. *If another field indicates direction of flow:* - Use one or more conditional rules to set the appropriate - amount sign. Eg: - - # assume a withdrawal unless Type contains "deposit": - amount1 -%Amount - if %Type deposit - amount1 %Amount - - 2. *If the amount is in two CSV fields (such as Debit and Credit, or - In and Out):* - - a. *If both fields are unsigned:* - Assign one field to 'amountN-in' and the other to - 'amountN-out'. hledger will automatically negate the "out" - field, and will use whichever field value is non-zero as - posting N's amount. - - b. *If either field is signed:* - You will probably need to override hledger's sign for one or - the other field, as in the following example: - - # Negate the -out value, but only if it is not empty: - fields date, description, amount1-in, amount1-out - if %amount1-out [1-9] - amount1-out -%amount1-out - - c. *If both fields can contain a non-zero value (or both can be - empty):* - The -in/-out rules normally choose the value which is - non-zero/non-empty. Some value pairs can be ambiguous, such - as '1' and 'none'. For such cases, use conditional rules to - help select the amount. Eg, to handle the above you could - select the value containing non-zero digits: - - fields date, description, in, out - if %in [1-9] - amount1 %in - if %out [1-9] - amount1 %out - - 3. *If you want posting 2's amount converted to cost:* - Use the unnumbered 'amount' (or 'amount-in' and 'amount-out') - syntax. - - 4. *If the CSV has only balance amounts, not transaction amounts:* - Assign to 'balanceN', to set a balance assignment on the Nth - posting, causing the posting's amount to be calculated - automatically. 'balance' with no number is equivalent to - 'balance1'. In this situation hledger is more likely to guess the - wrong default account name, so you may need to set that explicitly. - - -File: hledger.info, Node: Amount signs, Next: Setting currency/commodity, Prev: Setting amounts, Up: Working with CSV - -9.20.10 Amount signs --------------------- - -There is some special handling making it easier to parse and to reverse -amount signs. (This only works for whole amounts, not for cost amounts -such as COST in 'amount1 AMT @ COST'): - - * *If an amount value begins with a plus sign:* - that will be removed: '+AMT' becomes 'AMT' - - * *If an amount value is parenthesised:* - it will be de-parenthesised and sign-flipped: '(AMT)' becomes - '-AMT' - - * *If an amount value has two minus signs (or two sets of - parentheses, or a minus sign and parentheses):* - they cancel out and will be removed: '--AMT' or '-(AMT)' becomes - 'AMT' - - * *If an amount value contains just a sign (or just a set of - parentheses):* - that is removed, making it an empty value. '"+"' or '"-"' or - '"()"' becomes '""'. - - It's not possible (without preprocessing the CSV) to set an amount to -its absolute value, ie discard its sign. - - -File: hledger.info, Node: Setting currency/commodity, Next: Amount decimal places, Prev: Amount signs, Up: Working with CSV - -9.20.11 Setting currency/commodity ----------------------------------- - -If the currency/commodity symbol is included in the CSV's amount -field(s): - -2023-01-01,foo,$123.00 - - you don't have to do anything special for the commodity symbol, it -will be assigned as part of the amount. Eg: - -fields date,description,amount - -2023-01-01 foo - expenses:unknown $123.00 - income:unknown $-123.00 - - If the currency is provided as a separate CSV field: - -2023-01-01,foo,USD,123.00 - - You can assign that to the 'currency' pseudo-field, which has the -special effect of prepending itself to every amount in the transaction -(on the left, with no separating space): - -fields date,description,currency,amount - -2023-01-01 foo - expenses:unknown USD123.00 - income:unknown USD-123.00 - - Or, you can use a field assignment to construct the amount yourself, -with more control. Eg to put the symbol on the right, and separated by -a space: - -fields date,description,cur,amt -amount %amt %cur - -2023-01-01 foo - expenses:unknown 123.00 USD - income:unknown -123.00 USD - - Note we used a temporary field name ('cur') that is not 'currency' - -that would trigger the prepending effect, which we don't want here. - - -File: hledger.info, Node: Amount decimal places, Next: Referencing other fields, Prev: Setting currency/commodity, Up: Working with CSV - -9.20.12 Amount decimal places ------------------------------ - -When you are reading CSV data, eg with a command like 'hledger -f -foo.csv print', hledger will infer each commodity's decimal precision -(and other commodity display styles) from the amounts - much as when -reading a journal file without 'commodity' directives (see the link). - - Note, the commodity styles are not inferred from the numbers in the -original CSV data; rather, they are inferred from the amounts generated -by the CSV rules. - - When you are importing CSV data with the 'import' command, eg -'hledger import foo.csv', there's another step: 'import' tries to make -the new entries conform to the journal's existing styles. So for each -commodity - let's say it's EUR - 'import' will choose: - - 1. the style declared for EUR by a 'commodity' directive in the - journal - 2. otherwise, the style inferred from EUR amounts in the journal - 3. otherwise, the style inferred from EUR amounts generated by the CSV - rules. - - TLDR: if 'import' is not generating the precisions or styles you -want, add a 'commodity' directive to specify them. - - -File: hledger.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Amount decimal places, Up: Working with CSV - -9.20.13 Referencing other fields --------------------------------- - -In field assignments, you can interpolate only CSV fields, not hledger -fields. In the example below, there's both a CSV field and a hledger -field named amount1, but %amount1 always means the CSV field, not the -hledger field: - -# Name the third CSV field "amount1" -fields date,description,amount1 - -# Set hledger's amount1 to the CSV amount1 field followed by USD -amount1 %amount1 USD - -# Set comment to the CSV amount1 (not the amount1 assigned above) -comment %amount1 - - Here, since there's no CSV amount1 field, %amount1 will produce a -literal "amount1": - -fields date,description,csvamount -amount1 %csvamount USD -# Can't interpolate amount1 here -comment %amount1 - - When there are multiple field assignments to the same hledger field, -only the last one takes effect. Here, comment's value will be be B, or -C if "something" is matched, but never A: - -comment A -comment B -if something - comment C - - -File: hledger.info, Node: How CSV rules are evaluated, Next: Well factored rules, Prev: Referencing other fields, Up: Working with CSV - -9.20.14 How CSV rules are evaluated ------------------------------------ - -Here's how to think of CSV rules being evaluated. If you get a -confusing error while reading a CSV file, it may help to try to -understand which of these steps is failing: - - 1. Any included rules files are inlined, from top to bottom, depth - first (scanning each included file for further includes, - recursively, before proceeding). - - 2. Top level rules ('date-format', 'fields', 'newest-first', 'skip' - etc) are read, top to bottom. "Top level rules" means - non-conditional rules. If a rule occurs more than once, the last - one wins; except for 'skip'/'end' rules, where the first one wins. - - 3. The CSV file is read as text. Any non-ascii characters will be - decoded using the text encoding specified by the 'encoding' rule, - otherwise the system locale's text encoding. - - 4. Any top-level skip or end rule is applied. 'skip [N]' immediately - skips the current or next N CSV records; 'end' immediately skips - all remaining CSV records (not normally used at top level). - - 5. Now any remaining CSV records are processed. For each CSV record, - in file order: - - * Is there a conditional skip/end rule that applies for this - record ? Search the 'if' blocks, from top to bottom, for a - succeeding one containing a 'skip' or 'end' rule. If found, - skip the specified number of CSV records, then continue at 5. - Otherwise... - - * Do some basic validation on this CSV record (eg, check that it - has at least two fields). - - * For each hledger field ('date', 'description', 'account1', - etc.): - - 1. Get the field's assigned value, first searching top level - assignments, made directly or by the 'fields' rule, then - assignments made inside succeeding 'if' blocks. If there - are more than one, the last one wins. - - 2. Compute the field's actual value (as text), by - interpolating any %CSVFIELD references within the - assigned value; or by choosing a default value if there - was no assignment. - - * Generate a hledger transaction from the hledger field values, - parsing them if needed (eg from text to an amount). - - This is all done by the CSV reader, one of several readers hledger -can use to read transactions from an input file. When all input files -have been read successfully, their transactions are passed to whichever -hledger command the user specified. - - -File: hledger.info, Node: Well factored rules, Prev: How CSV rules are evaluated, Up: Working with CSV - -9.20.15 Well factored rules ---------------------------- - -Some things than can help reduce duplication and complexity in rules -files: - - * Extracting common rules usable with multiple CSV files into a - 'common.rules', and adding 'include common.rules' to each CSV's - rules file. - - * Splitting if blocks into smaller if blocks, extracting the - frequently used parts. - - -File: hledger.info, Node: CSV rules examples, Prev: Working with CSV, Up: CSV - -9.21 CSV rules examples -======================= - -* Menu: - -* Bank of Ireland:: -* Coinbase:: -* Amazon:: -* Paypal:: - - -File: hledger.info, Node: Bank of Ireland, Next: Coinbase, Up: CSV rules examples - -9.21.1 Bank of Ireland ----------------------- - -Here's a CSV with two amount fields (Debit and Credit), and a balance -field, which we can use to add balance assertions, which is not -necessary but provides extra error checking: - -Date,Details,Debit,Credit,Balance -07/12/2012,LODGMENT 529898,,10.0,131.21 -07/12/2012,PAYMENT,5,,126 - -# bankofireland-checking.csv.rules - -# skip the header line -skip - -# name the csv fields, and assign some of them as journal entry fields -fields date, description, amount-out, amount-in, balance - -# We generate balance assertions by assigning to "balance" -# above, but you may sometimes need to remove these because: -# -# - the CSV balance differs from the true balance, -# by up to 0.0000000000005 in my experience -# -# - it is sometimes calculated based on non-chronological ordering, -# eg when multiple transactions clear on the same day - -# date is in UK/Ireland format -date-format %d/%m/%Y - -# set the currency -currency EUR - -# set the base account for all txns -account1 assets:bank:boi:checking - -$ hledger -f bankofireland-checking.csv print -2012-12-07 LODGMENT 529898 - assets:bank:boi:checking EUR10.0 = EUR131.2 - income:unknown EUR-10.0 - -2012-12-07 PAYMENT - assets:bank:boi:checking EUR-5.0 = EUR126.0 - expenses:unknown EUR5.0 - - The balance assertions don't raise an error above, because we're -reading directly from CSV, but they will be checked if these entries are -imported into a journal file. - - -File: hledger.info, Node: Coinbase, Next: Amazon, Prev: Bank of Ireland, Up: CSV rules examples - -9.21.2 Coinbase ---------------- - -A simple example with some CSV from Coinbase. The spot price is -recorded using cost notation. The legacy 'amount' field name -conveniently sets amount 2 (posting 2's amount) to the total cost. - -# Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes -# 2021-12-30T06:57:59Z,Receive,USDC,100,GBP,0.740000,"","","","Received 100.00 USDC from an external account" - -# coinbase.csv.rules -skip 1 -fields Timestamp,Transaction_Type,Asset,Quantity_Transacted,Spot_Price_Currency,Spot_Price_at_Transaction,Subtotal,Total,Fees_Spread,Notes -date %Timestamp -date-format %Y-%m-%dT%T%Z -description %Notes -account1 assets:coinbase:cc -amount %Quantity_Transacted %Asset @ %Spot_Price_at_Transaction %Spot_Price_Currency - -$ hledger print -f coinbase.csv -2021-12-30 Received 100.00 USDC from an external account - assets:coinbase:cc 100 USDC @ 0.740000 GBP - income:unknown -74.000000 GBP - - -File: hledger.info, Node: Amazon, Next: Paypal, Prev: Coinbase, Up: CSV rules examples - -9.21.3 Amazon -------------- - -Here we convert amazon.com order history, and use an if block to -generate a third posting if there's a fee. (In practice you'd probably -get this data from your bank instead, but it's an example.) - -"Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID" -"Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL" -"Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL" - -# amazon-orders.csv.rules - -# skip one header line -skip 1 - -# name the csv fields, and assign the transaction's date, amount and code. -# Avoided the "status" and "amount" hledger field names to prevent confusion. -fields date, _, toorfrom, name, amzstatus, amzamount, fees, code - -# how to parse the date -date-format %b %-d, %Y - -# combine two fields to make the description -description %toorfrom %name - -# save the status as a tag -comment status:%amzstatus - -# set the base account for all transactions -account1 assets:amazon -# leave amount1 blank so it can balance the other(s). -# I'm assuming amzamount excludes the fees, don't remember - -# set a generic account2 -account2 expenses:misc -amount2 %amzamount -# and maybe refine it further: -#include categorisation.rules - -# add a third posting for fees, but only if they are non-zero. -if %fees [1-9] - account3 expenses:fees - amount3 %fees - -$ hledger -f amazon-orders.csv print -2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed - assets:amazon - expenses:misc $20.00 - -2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed - assets:amazon - expenses:misc $25.00 - expenses:fees $1.00 - - -File: hledger.info, Node: Paypal, Prev: Amazon, Up: CSV rules examples - -9.21.4 Paypal -------------- - -Here's a real-world rules file for (customised) Paypal CSV, with some -Paypal-specific rules, and a second rules file included: - -"Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note" -"10/01/2019","03:46:20","PDT","Calm Radio","Subscription Payment","Completed","USD","-6.99","0.00","-6.99","simon@joyful.com","memberships@calmradio.com","60P57143A8206782E","MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month","","I-R8YLY094FJYR","","-6.99","" -"10/01/2019","03:46:20","PDT","","Bank Deposit to PP Account ","Pending","USD","6.99","0.00","6.99","","simon@joyful.com","0TU1544T080463733","","","60P57143A8206782E","","0.00","" -"10/01/2019","08:57:01","PDT","Patreon","PreApproved Payment Bill User Payment","Completed","USD","-7.00","0.00","-7.00","simon@joyful.com","support@patreon.com","2722394R5F586712G","Patreon* Membership","","B-0PG93074E7M86381M","","-7.00","" -"10/01/2019","08:57:01","PDT","","Bank Deposit to PP Account ","Pending","USD","7.00","0.00","7.00","","simon@joyful.com","71854087RG994194F","Patreon* Membership","","2722394R5F586712G","","0.00","" -"10/19/2019","03:02:12","PDT","Wikimedia Foundation, Inc.","Subscription Payment","Completed","USD","-2.00","0.00","-2.00","simon@joyful.com","tle@wikimedia.org","K9U43044RY432050M","Monthly donation to the Wikimedia Foundation","","I-R5C3YUS3285L","","-2.00","" -"10/19/2019","03:02:12","PDT","","Bank Deposit to PP Account ","Pending","USD","2.00","0.00","2.00","","simon@joyful.com","3XJ107139A851061F","","","K9U43044RY432050M","","0.00","" -"10/22/2019","05:07:06","PDT","Noble Benefactor","Subscription Payment","Completed","USD","10.00","-0.59","9.41","noble@bene.fac.tor","simon@joyful.com","6L8L1662YP1334033","Joyful Systems","","I-KC9VBGY2GWDB","","9.41","" - -# paypal-custom.csv.rules - -# Tips: -# Export from Activity -> Statements -> Custom -> Activity download -# Suggested transaction type: "Balance affecting" -# Paypal's default fields in 2018 were: -# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Shipping Address","Address Status","Item Title","Item ID","Shipping and Handling Amount","Insurance Amount","Sales Tax","Option 1 Name","Option 1 Value","Option 2 Name","Option 2 Value","Reference Txn ID","Invoice Number","Custom Number","Quantity","Receipt ID","Balance","Address Line 1","Address Line 2/District/Neighborhood","Town/City","State/Province/Region/County/Territory/Prefecture/Republic","Zip/Postal Code","Country","Contact Phone Number","Subject","Note","Country Code","Balance Impact" -# This rules file assumes the following more detailed fields, configured in "Customize report fields": -# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note" - -fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note - -skip 1 - -date-format %-m/%-d/%Y - -# ignore some paypal events -if -In Progress -Temporary Hold -Update to - skip - -# add more fields to the description -description %description_ %itemtitle - -# save some other fields as tags -comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_ - -# convert to short currency symbols -if %currency USD - currency $ -if %currency EUR - currency E -if %currency GBP - currency P - -# generate postings - -# the first posting will be the money leaving/entering my paypal account -# (negative means leaving my account, in all amount fields) -account1 assets:online:paypal -amount1 %netamount - -# the second posting will be money sent to/received from other party -# (account2 is set below) -amount2 -%grossamount - -# if there's a fee, add a third posting for the money taken by paypal. -if %feeamount [1-9] - account3 expenses:banking:paypal - amount3 -%feeamount - comment3 business: - -# choose an account for the second posting - -# override the default account names: -# if the amount is positive, it's income (a debit) -if %grossamount ^[^-] - account2 income:unknown -# if negative, it's an expense (a credit) -if %grossamount ^- - account2 expenses:unknown - -# apply common rules for setting account2 & other tweaks -include common.rules - -# apply some overrides specific to this csv - -# Transfers from/to bank. These are usually marked Pending, -# which can be disregarded in this case. -if -Bank Account -Bank Deposit to PP Account - description %type for %referencetxnid %itemtitle - account2 assets:bank:wf:pchecking - account1 assets:online:paypal - -# Currency conversions -if Currency Conversion - account2 equity:currency conversion - -# common.rules - -if -darcs -noble benefactor - account2 revenues:foss donations:darcshub - comment2 business: - -if -Calm Radio - account2 expenses:online:apps - -if -electronic frontier foundation -Patreon -wikimedia -Advent of Code - account2 expenses:dues - -if Google - account2 expenses:online:apps - description google | music - -$ hledger -f paypal-custom.csv print -2019-10-01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed - assets:online:paypal $-6.99 = $-6.99 - expenses:online:apps $6.99 - -2019-10-01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending - assets:online:paypal $6.99 = $0.00 - assets:bank:wf:pchecking $-6.99 - -2019-10-01 (2722394R5F586712G) Patreon Patreon* Membership ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed - assets:online:paypal $-7.00 = $-7.00 - expenses:dues $7.00 - -2019-10-01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending - assets:online:paypal $7.00 = $0.00 - assets:bank:wf:pchecking $-7.00 - -2019-10-19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed - assets:online:paypal $-2.00 = $-2.00 - expenses:dues $2.00 - expenses:banking:paypal ; business: - -2019-10-19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending - assets:online:paypal $2.00 = $0.00 - assets:bank:wf:pchecking $-2.00 - -2019-10-22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed - assets:online:paypal $9.41 = $9.41 - revenues:foss donations:darcshub $-10.00 ; business: - expenses:banking:paypal $0.59 ; business: - - -File: hledger.info, Node: Timeclock, Next: Timedot, Prev: CSV, Up: Top - -10 Timeclock -************ - -hledger can read time logs in the timeclock time logging format of -timeclock.el. As with Ledger, hledger's timeclock format is a -subset/variant of timeclock.el's. - - hledger's timeclock format was updated in hledger 1.43 and 1.50. If -your old time logs are rejected, you should adapt them to modern -hledger; for now, you can restore the pre-1.43 behaviour with the -'--old-timeclock' flag. - - Here the timeclock format in hledger 1.50+: - -# Comment lines like these, and blank lines, are ignored: -# comment line -; comment line -* comment line - -# Lines beginning with b, h, or capital O are also ignored, for compatibility: -b SIMPLEDATE HH:MM[:SS][+-ZZZZ][ TEXT] -h SIMPLEDATE HH:MM[:SS][+-ZZZZ][ TEXT] -O SIMPLEDATE HH:MM[:SS][+-ZZZZ][ TEXT] - -# Lines beginning with i or o are are clock-in / clock-out entries: -i SIMPLEDATE HH:MM[:SS][+-ZZZZ] ACCOUNT[ DESCRIPTION][;COMMENT]] -o SIMPLEDATE HH:MM[:SS][+-ZZZZ][ ACCOUNT][;COMMENT] - - The date is a hledger simple date (YYYY-MM-DD or similar). The time -parts must use two digits. The seconds are optional. A + or - -four-digit time zone is accepted for compatibility, but currently -ignored; times are always interpreted as a local time. - - In clock-in entries ('i'), the account name is required. A -transaction description, separated from the account name by 2+ spaces, -is optional. A transaction comment, beginning with ';', is also -optional. (Indented following comment lines are also allowed, as in -journal format.) - - In clock-out entries ('o') have no description, but can have a -comment if you wish. A clock-in and clock-out pair form a "transaction" -posting some number of hours to an account - also known as a session. -Eg: - -i 2015/03/30 09:00:00 session1 -o 2015/03/30 10:00:00 - -$ hledger -f a.timeclock print -2015-03-30 * 09:00-10:00 - (session1) 1.00h - - Clock-ins and clock-outs are matched by their account/session name. -If a clock-out does not specify a name, the most recent unclosed -clock-in is closed. You can have multiple sessions active -simultaneously. Entries are processed in the order they are parsed. -Sessions spanning more than one day are automatically split at day -boundaries. - - Eg, the following time log: - -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 -i 2015/04/02 12:00:00 another:account ; this demonstrates multple sessions being clocked in -i 2015/04/02 13:00:00 some account -o 2015/04/02 14:00:00 -o 2015/04/02 15:00:00 another:account - - generates these transactions: - -$ 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 - -2015-04-02 * 12:00-15:00 ; this demonstrates multiple sessions being clocked in - (another:account) 3.00h - -2015-04-02 * 13:00-14:00 - (some account) 1.00h - - Here is a sample.timeclock to download and some queries to try: - -$ hledger -f sample.timeclock balance # current time balances -$ hledger -f sample.timeclock register -p 2009/3 # sessions in march 2009 -$ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week - - To generate time logs, ie to clock in and clock out, you could: - - * use these shell aliases at the command line: - - alias ti='echo i `date "+%Y-%m-%d %H:%M:%S"` $* >>$TIMELOG' - alias to='echo o `date "+%Y-%m-%d %H:%M:%S"` >>$TIMELOG' - - * or Emacs's built-in timeclock.el, or the extended timeclock-x.el, - and perhaps the extras in ledgerutils.el - - * or use the old 'ti' and 'to' scripts in the ledger 2.x repository. - These rely on a "timeclock" executable which I think is just the - ledger 2 executable renamed. - - -File: hledger.info, Node: Timedot, Next: PART 3 REPORTING CONCEPTS, Prev: Timeclock, Up: Top - -11 Timedot -********** - -'timedot' format is hledger's human-friendly time logging format. -Compared to 'timeclock' format, it is more convenient for quick, -approximate, and retroactive time logging, and more human-readable (you -can see at a glance where time was spent). A quick example: - -2023-05-01 -hom:errands .... .... ; two hours; the space is ignored -fos:hledger:timedot .. ; half an hour -per:admin:finance ; no time spent yet - - hledger reads this as a transaction on this day with three -(unbalanced) postings, where each dot represents "0.25". No commodity -symbol is assumed, but we typically interpret it as hours. - -$ hledger -f a.timedot print # .timedot file extension (or timedot: prefix) is required -2023-05-01 * - (hom:errands) 2.00 ; two hours - (fos:hledger:timedot) 0.50 ; half an hour - (per:admin:finance) 0 - - A timedot file contains a series of transactions (usually one per -day). Each begins with a *simple date* (Y-M-D, Y/M/D, or Y.M.D), -optionally be followed on the same line by a transaction description, -and/or a transaction comment following a semicolon. - - After the date line are zero or more time postings, consisting of: - - * *An account name* - any hledger-style account name, optionally - indented. - - * *Two or more spaces* - required if there is an amount (as in - journal format). - - * *A timedot amount*, which can be - - * empty (representing zero) - - * a number, optionally followed by a unit 's', 'm', 'h', 'd', - 'w', 'mo', or 'y', representing a precise number of seconds, - minutes, hours, days weeks, months or years (hours is assumed - by default), which will be converted to hours according to 60s - = 1m, 60m = 1h, 24h = 1d, 7d = 1w, 30d = 1mo, 365d = 1y. - - * one or more dots (period characters), each representing 0.25. - These are the dots in "timedot". Spaces are ignored and can - be used for grouping/alignment. - - * _Added in 1.32_ one or more letters. These are like dots but - they also generate a tag 't:' (short for "type") with the - letter as its value, and a separate posting for each of the - values. This provides a second dimension of categorisation, - viewable in reports with '--pivot t'. - - * *An optional comment* following a semicolon (a hledger-style - posting comment). - - There is some flexibility to help with keeping time log data and -notes in the same file: - - * Blank lines and lines beginning with '#' or ';' are ignored. - - * After the first date line, lines which do not contain a double - space are parsed as postings with zero amount. (hledger's register - reports will show these if you add -E). - - * Before the first date line, lines beginning with '*' (eg org - headings) are ignored. And from the first date line onward, Emacs - org mode heading prefixes at the start of lines (one or more '*''s - followed by a space) will be ignored. This means the time log can - also be a org outline. - - Timedot files don't support directives like journal files. So a -common pattern is to have a main journal file (eg 'time.journal') that -contains any needed directives, and then includes the timedot file -('include time.timedot'). - -* Menu: - -* Timedot examples:: - - -File: hledger.info, Node: Timedot examples, Up: Timedot - -11.1 Timedot examples -===================== - -Numbers: - -2016/2/3 -inc:client1 4 -fos:hledger 3h -biz:research 60m - - Dots: - -# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc. -2016/2/1 -inc:client1 .... .... .... .... .... .... -fos:haskell .... .. -biz:research . - -2016/2/2 -inc:client1 .... .... -biz:research . - -$ hledger -f a.timedot print date:2016/2/2 -2016-02-02 * - (inc:client1) 2.00 - -2016-02-02 * - (biz:research) 0.25 - -$ hledger -f a.timedot bal --daily --tree -Balance changes in 2016-02-01-2016-02-03: - - || 2016-02-01d 2016-02-02d 2016-02-03d -============++======================================== - biz || 0.25 0.25 1.00 - research || 0.25 0.25 1.00 - fos || 1.50 0 3.00 - haskell || 1.50 0 0 - hledger || 0 0 3.00 - inc || 6.00 2.00 4.00 - client1 || 6.00 2.00 4.00 -------------++---------------------------------------- - || 7.75 2.25 8.00 - - Letters: - -# Activity types: -# c cleanup/catchup/repair -# e enhancement -# s support -# l learning/research - -2023-11-01 -work:adm ccecces - -$ hledger -f a.timedot print -2023-11-01 - (work:adm) 1 ; t:c - (work:adm) 0.5 ; t:e - (work:adm) 0.25 ; t:s - -$ hledger -f a.timedot bal - 1.75 work:adm --------------------- - 1.75 - -$ hledger -f a.timedot bal --pivot t - 1.00 c - 0.50 e - 0.25 s --------------------- - 1.75 - - Org: - -* 2023 Work Diary -** Q1 -*** 2023-02-29 -**** DONE -0700 yoga -**** UNPLANNED -**** BEGUN -hom:chores - cleaning ... - water plants - outdoor - one full watering can - indoor - light watering -**** TODO -adm:planning: trip -*** LATER - - Using '.' as account name separator: - -2016/2/4 -fos.hledger.timedot 4h -fos.ledger .. - -$ hledger -f a.timedot --alias '/\./=:' bal -t - 4.50 fos - 4.00 hledger:timedot - 0.50 ledger --------------------- - 4.50 - - -File: hledger.info, Node: PART 3 REPORTING CONCEPTS, Next: Time periods, Prev: Timedot, Up: Top - -12 PART 3: REPORTING CONCEPTS -***************************** - - -File: hledger.info, Node: Time periods, Next: Depth, Prev: PART 3 REPORTING CONCEPTS, Up: Top - -13 Time periods -*************** - -* Menu: - -* Report start & end date:: -* Smart dates:: -* Report intervals:: -* Date adjustments:: -* Period headings:: -* Period expressions:: - - -File: hledger.info, Node: Report start & end date, Next: Smart dates, Up: Time periods - -13.1 Report start & end date -============================ - -Most hledger reports will by default show the full time period -represented by the journal. The report start date will be the earliest -transaction or posting date, and the report end date will be the latest -transaction, posting, or market price date. - - Often you will want to see a shorter period, such as the current -month. You can specify a start and/or end date with the '-b/--begin', -'-e/--end', or '-p/--period' options, or a 'date:' query argument, -described below. All of these accept the smart date syntax, also -described below. - - End dates are exclusive; specify the day after the last day you want -to see in the report. - - When dates are specified by multiple options, the last (right-most) -option wins. And when 'date:' queries and date options are combined, -the report period will be their intersection. - - Examples: - -'-b 2016/3/17' - - beginning on St. Patrick's day 2016 -'-e 12/1' - - ending at the start of December 1st in the current year -'-p 'this month'' - - during the current month -'-p thismonth' - - same as above, spaces are optional -'-b 2023' - - beginning on the first day of 2023 -'date:2023..' or 'date:2023-' - - same as above - - '-b 2024 -e 2025 -p '2000 to 2030' date:2020-01 date:2020' : -during January 2020 (the smallest common period, with the -p overriding --b and -e) - - -File: hledger.info, Node: Smart dates, Next: Report intervals, Prev: Report start & end date, Up: Time periods - -13.2 Smart dates -================ - -In hledger's user interfaces (though not in the journal file), you can -optionally use "smart date" syntax. Smart dates can be written with -english words, can be relative, and can have parts omitted. Missing -parts are inferred as 1, when needed. Smart dates can be interpreted as -dates or periods depending on the context. - - Examples: - - '2004-01-01', '2004/10/1', '2004.9.1', '20240504', '2024Q1' : -Exact dates. The year must have at least four digits, the month must be -1-12, the day must be 1-31, the separator can be '-' or '/' or '.' or -nothing. The q can be upper or lower case and the quarter number must -be 1-4. - -'2004-10' - - start of month -'2004q3' - - start of third quarter of 2004 -'q3' - - start of third quarter of current year -'2004' - - start of year -'10/1' or 'oct' or 'october' - - October 1st in current year -'21' - - 21st day in current month -'yesterday, today, tomorrow' - - -1, 0, 1 days from today -'last/this/next day/week/month/quarter/year' - - -1, 0, 1 periods from the current period -'in n days/weeks/months/quarters/years' - - n periods from the current period -'n days/weeks/months/quarters/years ahead' - - n periods from the current period -'n days/weeks/months/quarters/years ago' - - -n periods from the current period -'20181201' - - 8 digit YYYYMMDD with valid year month and day -'201812' - - 6 digit YYYYMM with valid year and month - - Dates with no separators are allowed but might give surprising -results if mistyped: - - * '20181301' (YYYYMMDD with an invalid month) is parsed as an - eight-digit year - * '20181232' (YYYYMMDD with an invalid day) gives a parse error - * '201801012' (a valid YYYYMMDD followed by additional digits) gives - a parse error - - The meaning of relative dates depends on today's date. If you need -to test or reproduce old reports, you can use the '--today' option to -override that. (Except for periodic transaction rules, which are not -affected by '--today'.) - - -File: hledger.info, Node: Report intervals, Next: Date adjustments, Prev: Smart dates, Up: Time periods - -13.3 Report intervals -===================== - -A report interval can be specified so that reports like register, -balance or activity become multi-period, showing each subperiod as a -separate row or column. - - The following standard intervals can be enabled with command-line -flags: - - * '-D/--daily' - * '-W/--weekly' - * '-M/--monthly' - * '-Q/--quarterly' - * '-Y/--yearly' - - More complex intervals can be specified using '-p/--period', -described below. - - -File: hledger.info, Node: Date adjustments, Next: Period headings, Prev: Report intervals, Up: Time periods - -13.4 Date adjustments -===================== - -* Menu: - -* Start date adjustment:: -* End date adjustment:: - - -File: hledger.info, Node: Start date adjustment, Next: End date adjustment, Up: Date adjustments - -13.4.1 Start date adjustment ----------------------------- - -If you let hledger infer a report's start date, it will adjust the date -to the previous natural boundary of the report interval, for convenient -periodic reports. (If you don't want that, specify a start date.) - - For example, if the journal's first transaction is on january 10th, - - * 'hledger register' (no report interval) will start the report on - january 10th. - * 'hledger register --monthly' will start the report on the previous - month boundary, january 1st. - * 'hledger register --monthly --begin 1/5' will start the report on - january 5th [1]. - - Also if you are generating transactions or budget goals with periodic -transaction rules, their start date may be adjusted in a similar way (in -certain situations). - - -File: hledger.info, Node: End date adjustment, Prev: Start date adjustment, Up: Date adjustments - -13.4.2 End date adjustment --------------------------- - -A report's end date is always adjusted to include a whole number of -intervals, so that the last subperiod has the same length as the others. - - For example, if the journal's last transaction is on february 20th, - - * 'hledger register' will end the report on february 20th. - * 'hledger register --monthly' will end the report at the end of - february. - * 'hledger register --monthly --end 2/14' also will end the report at - the end of february (overriding the requested end date). - * 'hledger register --monthly --begin 1/5 --end 2/14' will end the - report on march 4th [1]. - - [1] Since hledger 1.29. - - -File: hledger.info, Node: Period headings, Next: Period expressions, Prev: Date adjustments, Up: Time periods - -13.5 Period headings -==================== - -With non-standard subperiods, hledger will show "STARTDATE..ENDDATE" -headings. With standard subperiods (ie, starting on a natural interval -boundary), you'll see more compact headings, which are usually -preferable. (Though month names will be in english, currently.) - - So if you are specifying a start date and you want compact headings: -choose a start of year for yearly reports, a start of quarter for -quarterly reports, a start of month for monthly reports, etc. -(Remember, you can write eg '-b 2024' or '1/1' as a shortcut for a start -of year, or '2024-04' or '202404' or 'Apr' for a start of month or -quarter.) - - For weekly reports, choose a date that's a Monday. (You can try -different dates until you see the short headings, or write eg '-b '3 -weeks ago''.) - - -File: hledger.info, Node: Period expressions, Prev: Period headings, Up: Time periods - -13.6 Period expressions -======================= - -The '-p/--period' option specifies a period expression, which is a -compact way of expressing a start date, end date, and/or report -interval. - - Here's a period expression with a start and end date (specifying the -first quarter of 2009): - -'-p "from 2009/1/1 to 2009/4/1"' - - Several keywords like "from" and "to" are supported for readability; -these are optional. "to" can also be written as ".." or "-". The -spaces are also optional, as long as you don't run two dates together. -So the following are equivalent to the above: - -'-p "2009/1/1 2009/4/1"' -'-p2009/1/1to2009/4/1' -'-p2009/1/1..2009/4/1' - - Dates are smart dates, so if the current year is 2009, these are also -equivalent to the above: - -'-p "1/1 4/1"' -'-p "jan-apr"' -'-p "this year to 4/1"' - - If you specify only one date, the missing start or end date will be -the earliest or latest transaction date in the journal: - -'-p "from 2009/1/1"' everything after january 1, 2009 -'-p "since 2009/1"' the same, since is a synonym -'-p "from 2009"' the same -'-p "to 2009"' everything before january 1, 2009 - - You can also specify a period by writing a single partial or full -date: - -'-p "2009"' the year 2009; equivalent to “2009/1/1 to 2010/1/1” -'-p "2009/1"' the month of january 2009; equivalent to “2009/1/1 to - 2009/2/1” -'-p the first day of 2009; equivalent to “2009/1/1 to -"2009/1/1"' 2009/1/2” - - or by using the "Q" quarter-year syntax (case insensitive): - -'-p "2009Q1"' first quarter of 2009, equivalent to “2009/1/1 to - 2009/4/1” -'-p "q4"' fourth quarter of the current year - -* Menu: - -* Period expressions with a report interval:: -* More complex report intervals:: -* Multiple weekday intervals:: - - -File: hledger.info, Node: Period expressions with a report interval, Next: More complex report intervals, Up: Period expressions - -13.6.1 Period expressions with a report interval ------------------------------------------------- - -A period expression can also begin with a report interval, separated -from the start/end dates (if any) by a space or the word 'in': - -'-p "weekly from 2009/1/1 to 2009/4/1"' -'-p "monthly in 2008"' -'-p "quarterly"' - - -File: hledger.info, Node: More complex report intervals, Next: Multiple weekday intervals, Prev: Period expressions with a report interval, Up: Period expressions - -13.6.2 More complex report intervals ------------------------------------- - -Some more complex intervals can be specified within period expressions, -such as: - - * 'biweekly' (every two weeks) - * 'fortnightly' - * 'bimonthly' (every two months) - * 'every day|week|month|quarter|year' - * 'every N days|weeks|months|quarters|years' - - Weekly on a custom day: - - * 'every Nth day of week' ('th', 'nd', 'rd', or 'st' are all accepted - after the number) - * 'every WEEKDAYNAME' (full or three-letter english weekday name, - case insensitive) - - Monthly on a custom day: - - * 'every Nth day [of month]' ('31st day' will be adjusted to each - month's last day) - * 'every Nth WEEKDAYNAME [of month]' - - Yearly on a custom month and day: - - * 'every MM/DD [of year]' (month number and day of month number) - * 'every MONTHNAME DDth [of year]' (full or three-letter english - month name, case insensitive, and day of month number) - * 'every DDth MONTHNAME [of year]' (equivalent to the above) - - Examples: - -'-p "bimonthly from -2008"' -'-p "every 2 weeks"' -'-p "every 5 months from -2009/03"' -'-p "every 2nd day of periods will go from Tue to Tue -week"' -'-p "every Tue"' same -'-p "every 15th day"' period boundaries will be on 15th of each - month -'-p "every 2nd Monday"' period boundaries will be on second Monday - of each month -'-p "every 11/05"' yearly periods with boundaries on 5th of - November -'-p "every 5th November"' same -'-p "every Nov 5th"' same - - Show historical balances at end of the 15th day of each month (N is -an end date, exclusive as always): - -$ hledger balance -H -p "every 16th day" - - Group postings from the start of wednesday to end of the following -tuesday (N is both (inclusive) start date and (exclusive) end date): - -$ hledger register checking -p "every 3rd day of week" - - -File: hledger.info, Node: Multiple weekday intervals, Prev: More complex report intervals, Up: Period expressions - -13.6.3 Multiple weekday intervals ---------------------------------- - -This special form is also supported: - - * 'every WEEKDAYNAME,WEEKDAYNAME,...' (full or three-letter english - weekday names, case insensitive) - - Also, 'weekday' and 'weekendday' are shorthand for -'mon,tue,wed,thu,fri' and 'sat,sun'. - - This is mainly intended for use with '--forecast', to generate -periodic transactions on arbitrary days of the week. It may be less -useful with '-p', since it divides each week into subperiods of unequal -length, which is unusual. (Related: #1632) - - Examples: - -'-p "every dates will be Mon, Wed, Fri; periods will be -mon,wed,fri"' Mon-Tue, Wed-Thu, Fri-Sun -'-p "every dates will be Mon, Tue, Wed, Thu, Fri; periods will -weekday"' be Mon, Tue, Wed, Thu, Fri-Sun -'-p "every dates will be Sat, Sun; periods will be Sat, Sun-Fri -weekendday"' - - -File: hledger.info, Node: Depth, Next: Queries, Prev: Time periods, Up: Top - -14 Depth -******** - -With the '--depth NUM' option (short form: '-NUM'), reports will show -accounts only to the specified depth, hiding deeper subaccounts. Use -this when you want a summary with less detail. This flag has the same -effect as a 'depth:' query argument. So all of these are equivalent: -'depth:2', '--depth=2', '-2'. - - In place of a single number which limits the depth for all accounts, -you can also provide depth limits for specific accounts, by providing a -'REGEX=DEPTH' argument instead of just a 'DEPTH' _(since 1.41)_. For -example, '--depth assets=2' (or 'depth:assets=2') will collapse accounts -matching the regular expression "assets" to depth 2. So -'assets:bank:savings' would be collapsed to 'assets:bank', but -'liabilities:bank:credit card' would not be affected. - - (If REGEX contains spaces or other special characters, enclose it in -quotes in the usual way. Eg: '--depth 'credit card=2'') - - Specific depth options and a general depth option can be combined. -Eg '--depth assets=3 --depth expenses=2 --depth 1' would collapse -accounts containing "assets" to depth 3, accounts containing "expenses" -to depth 2, and all other accounts to depth 1. - - If an account is matched by more than one regular expression depth -argument, the most specific (deepest) match will be used. For example, -with '--depth assets=1 --depth savings=2', 'assets:bank:savings' will be -collapsed to depth 2, not depth 1 (because "savings" matches a deeper -part of it than "assets" does). - - -File: hledger.info, Node: Queries, Next: Pivoting, Prev: Depth, Up: Top - -15 Queries -********** - -Many hledger commands accept query arguments, which restrict their scope -and let you report on a precise subset of your data. Here's a quick -overview of hledger's queries: - - * By default, a query argument is treated as a case-insensitive - substring pattern for matching account names. Eg: - - 'dining groceries' - 'car:fuel' - - * Patterns containing spaces or other special characters must be - enclosed in single or double quotes: - - ''personal care'' - - * Patterns are actually regular expressions, so you can add regexp - metacharacters for more precision (or you may need to - backslash-escape certain characters; see "Regular expressions" - above): - - ''^expenses\b'' - ''food$'' - ''fuel|repair'' - ''accounts (payable|receivable)'' - - * To match something other than the account name, you can add a query - type prefix, such as: - - 'date:202312-' - 'status:' - 'desc:amazon' - 'cur:USD' - 'cur:\\$' - 'amt:'>0'' - 'acct:groceries' (but 'acct:' is the default, so we usually don't - bother writing it) - - * To negate a query, add a 'not:' prefix: - - 'not:status:'*'' - 'not:desc:'opening|closing'' - 'not:cur:USD' - - * Multiple query terms can be combined, as space-separated queries - Eg: 'hledger print date:2022 desc:amazon desc:amzn' (show - transactions dated in 2022 whose description contains "amazon" or - "amzn"). - - * Or more flexibly as boolean queries. Eg: 'hledger print - expr:'date:2022 and (desc:amazon or desc:amzn) and not - date:202210'' - - All hledger commands use the same query language, but different -commands may interpret the query in different ways. We haven't -described the commands yet (that's coming in PART 4: COMMANDS below) but -here's the gist of it: - - * Transaction-oriented commands ('print', 'aregister', 'close', - 'import', 'descriptions'..) try to match transactions (including - the transaction's postings). - - * Posting-oriented commands ('register', 'balance', 'balancesheet', - 'incomestatement', 'accounts'..) try to match postings. Postings - inherit their transaction's attributes for querying purposes, so - transaction fields like date or description can still be referenced - in a posting query. - - * A few commands match in more specific ways. (Eg 'aregister', which - has a special first argument.) - -* Menu: - -* Query types:: -* Negative queries:: -* Space-separated queries:: -* Boolean queries:: -* Queries and command options:: -* Queries and account aliases:: -* Queries and valuation:: - - -File: hledger.info, Node: Query types, Next: Negative queries, Up: Queries - -15.1 Query types -================ - -Here are the query types available: - -* Menu: - -* acct query:: -* amt query:: -* code query:: -* cur query:: -* desc query:: -* date query:: -* date2 query:: -* depth query:: -* note query:: -* payee query:: -* real query:: -* status query:: -* type query:: -* tag query:: - - -File: hledger.info, Node: acct query, Next: amt query, Up: Query types - -15.1.1 acct: query ------------------- - -*'acct:REGEX'*, or just *'REGEX'* -Match account names containing this case insensitive regular expression. -This is the default query type, so we usually don't bother writing the -"acct:" prefix. - - -File: hledger.info, Node: amt query, Next: code query, Prev: acct query, Up: Query types - -15.1.2 amt: query ------------------ - -*'amt:N, amt:'N', amt:'>=N''* -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.) 'amt:' needs quotes to hide the less -than/greater than sign from the command line shell. - - 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. - - Keep in mind that 'amt:' matches posting amounts, not account -balances. - - -File: hledger.info, Node: code query, Next: cur query, Prev: amt query, Up: Query types - -15.1.3 code: query ------------------- - -*'code:REGEX'* -Match by transaction code (eg check number). - - -File: hledger.info, Node: cur query, Next: desc query, Prev: code query, Up: Query types - -15.1.4 cur: query ------------------ - -*'cur:REGEX'* -Match postings or transactions including any amounts whose -currency/commodity symbol is fully matched by REGEX. (Contrary to -hledger's usual infix matching. To do infix matching, write -'.*REGEX.*'.) Note, to match special characters which are -regex-significant, you need to escape them with '\'. And for characters -which are significant to your shell you will usually need one more level -of escaping. Eg to match the dollar sign: 'cur:\\$' or 'cur:'\$'' - - -File: hledger.info, Node: desc query, Next: date query, Prev: cur query, Up: Query types - -15.1.5 desc: query ------------------- - -*'desc:REGEX'* -Match transaction descriptions. - - -File: hledger.info, Node: date query, Next: date2 query, Prev: desc query, Up: Query types - -15.1.6 date: query ------------------- - -*'date:PERIODEXPR'* -Match dates (or with the '--date2' flag, secondary dates) within the -specified period. PERIODEXPR is a period expression with no report -interval. Examples: -'date:2016', 'date:thismonth', 'date:2/1-2/15', -'date:2021-07-27..nextquarter'. - - -File: hledger.info, Node: date2 query, Next: depth query, Prev: date query, Up: Query types - -15.1.7 date2: query -------------------- - -*'date2:PERIODEXPR'* -If you use secondary dates: this matches secondary dates within the -specified period. It is not affected by the '--date2' flag. - - -File: hledger.info, Node: depth query, Next: note query, Prev: date2 query, Up: Query types - -15.1.8 depth: query -------------------- - -*'depth:[REGEXP=]N'* -Match (or display, depending on command) accounts at or above this -depth, optionally only for accounts matching a provided regular -expression. See Depth for detailed rules. - - -File: hledger.info, Node: note query, Next: payee query, Prev: depth query, Up: Query types - -15.1.9 note: query ------------------- - -*'note:REGEX'* -Match transaction notes (the part of the description right of '|', or -the whole description if there's no '|'). - - -File: hledger.info, Node: payee query, Next: real query, Prev: note query, Up: Query types - -15.1.10 payee: query --------------------- - -*'payee:REGEX'* -Match transaction payee/payer names (the part of the description left of -'|', or the whole description if there's no '|'). - - -File: hledger.info, Node: real query, Next: status query, Prev: payee query, Up: Query types - -15.1.11 real: query -------------------- - -*'real:, real:0'* -Match real or virtual postings respectively. - - -File: hledger.info, Node: status query, Next: type query, Prev: real query, Up: Query types - -15.1.12 status: query ---------------------- - -*'status:, status:!, status:*'* -Match unmarked, pending, or cleared transactions respectively. - - -File: hledger.info, Node: type query, Next: tag query, Prev: status query, Up: Query types - -15.1.13 type: query -------------------- - -*'type:TYPECODES'* -Match by account type (see Declaring accounts > Account types). -'TYPECODES' is one or more of the single-letter account type codes -'ALERXCV', case insensitive. Note 'type:A' and 'type:E' will also match -their respective subtypes 'C' (Cash) and 'V' (Conversion). Certain -kinds of account alias can disrupt account types, see Rewriting accounts -> Aliases and account types. - - -File: hledger.info, Node: tag query, Prev: type query, Up: Query types - -15.1.14 tag: query ------------------- - -*'tag:NAMEREGEX[=VALREGEX]'* -Match by tag name, and optionally also by tag value. Note: - - * Both regular expressions do infix matching. If you need a complete - match, use '^' and '$'. - Eg: 'tag:'^fullname$'', 'tag:'^fullname$=^fullvalue$' - * To match values, ignoring names, do 'tag:.=VALREGEX' - * Accounts also inherit the tags of their parent accounts. - * Postings also inherit the tags of their account and their - transaction . - * Transactions also acquire the tags of their postings. - - -File: hledger.info, Node: Negative queries, Next: Space-separated queries, Prev: Query types, Up: Queries - -15.2 Negative queries -===================== - -* Menu: - -* not query:: - - -File: hledger.info, Node: not query, Up: Negative queries - -15.2.1 not: query ------------------ - -*'not:QUERY'* -You can prepend *'not:'* to a query to negate the match. -Eg: 'not:equity', 'not:desc:apple' -(Also, a trick: 'not:not:...' can sometimes solve query problems -conveniently.) - - -File: hledger.info, Node: Space-separated queries, Next: Boolean queries, Prev: Negative queries, Up: Queries - -15.3 Space-separated queries -============================ - -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. - - -File: hledger.info, Node: Boolean queries, Next: Queries and command options, Prev: Space-separated queries, Up: Queries - -15.4 Boolean queries -==================== - -You can write more complicated "boolean" query expressions, enclosed in -quotes and prefixed with 'expr:'. These can combine subqueries with -NOT, AND, OR operators (case insensitive), and parentheses for grouping. -Eg, to show transactions involving both cash and expense accounts: - -hledger print expr:'cash AND expenses' - - The prefix and enclosing quotes are required, so don't write 'hledger -print cash AND expenses'. That would be a space-separated query showing -transactions involving accounts with any of "cash", "and", "expenses" in -their names. - - You can write space-separated queries _inside_ a boolean query, and -they will combine as described above, but it might be confusing and best -avoided. Eg these are equivalent, showing transactions involving cash -or expenses accounts: - -hledger print expr:'cash expenses' -hledger print cash expenses - - There is a restriction with 'date:' queries: they may not be used -inside OR expressions. - - Actually, there are three types of boolean query: 'expr:' for general -use, and 'any:' and 'all:' variants which can be useful with 'print'. - -* Menu: - -* expr query:: -* any query:: -* all query:: - - -File: hledger.info, Node: expr query, Next: any query, Up: Boolean queries - -15.4.1 expr: query ------------------- - -*'expr:'QUERYEXPR''* -For example, 'expr:'date:lastmonth AND NOT (food OR rent)'' means "match -things which are dated in the last month and do not have food or rent in -the account name". - - When using 'expr:' with transaction-oriented commands like 'print', -posting-oriented query terms like 'acct:' and 'amt:' are considered to -match the transaction if they match any of its postings. -So, 'hledger print expr:'cash and amt:>0'' means "show transactions with -(at least one posting involving a cash account) and (at least one -posting with a positive amount)". - - -File: hledger.info, Node: any query, Next: all query, Prev: expr query, Up: Boolean queries - -15.4.2 any: query ------------------ - -*'any:'QUERYEXPR''* -Like 'expr:', but when used with transaction-oriented commands like -'print', it matches the transaction only if a posting can be matched by -all of QUERYEXPR. -So, 'hledger print any:'cash and amt:>0'' means "show transactions where -at least one posting posts a positive amount to a cash account". - - -File: hledger.info, Node: all query, Prev: any query, Up: Boolean queries - -15.4.3 all: query ------------------ - -*'all:'QUERYEXPR''* -Like 'expr:', but when used with transaction-oriented commands like -'print', it matches the transaction only if all postings are matched by -all of QUERYEXPR (and there is at least one posting). -So, 'hledger print all:'cash and amt:0'' means "show transactions where -all postings involve a cash account and have a zero amount". -Or, 'hledger print all:'cash or checking'' means "show transactions -which touch only cash and/or checking accounts". - - -File: hledger.info, Node: Queries and command options, Next: Queries and account aliases, Prev: Boolean queries, Up: Queries - -15.5 Queries and command options -================================ - -Some queries can also be expressed as command-line options: 'depth:2' is -equivalent to '--depth 2', 'date:2023' is equivalent to '-p 2023', etc. -When you mix command options and query arguments, generally the -resulting query is their intersection. - - -File: hledger.info, Node: Queries and account aliases, Next: Queries and valuation, Prev: Queries and command options, Up: Queries - -15.6 Queries and account aliases -================================ - -When account names are rewritten with '--alias' or 'alias', 'acct:' will -match either the old or the new account name. - - -File: hledger.info, Node: Queries and valuation, Prev: Queries and account aliases, Up: Queries - -15.7 Queries and valuation -========================== - -When amounts are converted to other commodities in cost or value -reports, 'cur:' and 'amt:' match the old commodity symbol and the old -amount quantity, not the new ones. (Except in hledger 1.22, #1625.) - - -File: hledger.info, Node: Pivoting, Next: Generating data, Prev: Queries, Up: Top - -16 Pivoting -*********** - -Normally, hledger groups amounts and displays their totals by account -(name). With '--pivot PIVOTEXPR', some other field's (or multiple -fields') value is used as a synthetic account name, causing different -grouping and display. PIVOTEXPR can be - - * any of these standard transaction or posting fields (their value is - substituted): 'status', 'code', 'desc', 'payee', 'note', 'acct', - 'comm'/'cur', 'amt', 'cost' - * or a tag name - * or any combination of these, colon-separated. - - Some special cases: - - * Colons appearing in PIVOTEXPR or in a pivoted tag value will - generate account hierarchy. - * When pivoting a posting has multiple values for a tag, the pivoted - value of that tag will be the first value. - * When a posting has multiple commodities, the pivoted value of - "comm"/"cur" will be "". Also when an unrecognised tag name or - field is provided, its pivoted value will be "". (If this causes - confusing output, consider excluding those postings from the - report.) - - Examples: - -2016/02/16 Yearly Dues Payment - assets:bank account 2 EUR - income:dues -2 EUR ; member: John Doe, kind: Lifetime - - Normal balance report showing account names: - -$ hledger balance - 2 EUR assets:bank account - -2 EUR income:dues --------------------- - 0 - - Pivoted balance report, using member: tag values instead: - -$ hledger balance --pivot member - 2 EUR - -2 EUR John Doe --------------------- - 0 - - One way to show only amounts with a member: value (using a query): - -$ hledger balance --pivot member tag:member=. - -2 EUR John Doe --------------------- - -2 EUR - - Another way (the acct: query matches against the pivoted "account -name"): - -$ hledger balance --pivot member acct:. - -2 EUR John Doe --------------------- - -2 EUR - - Hierarchical reports can be generated with multiple pivot values: - -$ hledger balance Income:Dues --pivot kind:member - -2 EUR Lifetime:John Doe --------------------- - -2 EUR - - -File: hledger.info, Node: Generating data, Next: Forecasting, Prev: Pivoting, Up: Top - -17 Generating data -****************** - -hledger can enrich the data provided to it, or generate new data, in a -number of ways. Mostly, this is done only if you request it: - - * Missing amounts or missing costs in transactions are inferred - automatically when possible. - * The '--infer-equity' flag infers missing conversion equity postings - from @/@@ costs. - * The '--infer-costs' flag infers missing costs from conversion - equity postings. - * The '--infer-market-prices' flag infers 'P' price directives from - costs. - * The '--auto' flag adds extra postings to transactions matched by - auto posting rules. - * The '--forecast' option generates transactions from periodic - transaction rules. - * The 'balance --budget' report infers budget goals from periodic - transaction rules. - * Commands like 'close', 'rewrite', and 'hledger-interest' generate - transactions or postings. - * CSV data is converted to transactions by applying CSV conversion - rules.. etc. - - Such generated data is temporary, existing only at report time. You -can convert it to permanent recorded data by, eg, capturing the output -of 'hledger print' and saving it in your journal file. This can -sometimes be useful as a data entry aid. - - If you are curious what data is being generated and why, run 'hledger -print -x --verbose-tags'. '-x/--explicit' shows inferred amounts and -'--verbose-tags' adds tags like 'generated-transaction' (from periodic -rules) and 'generated-posting', 'modified' (from auto posting rules). -Similar hidden tags (with an underscore prefix) are always present, -also, so you can always match such data with queries like -'tag:generated' or 'tag:modified'. - - -File: hledger.info, Node: Forecasting, Next: Budgeting, Prev: Generating data, Up: Top - -18 Forecasting -************** - -Forecasting, or speculative future reporting, can be useful for -estimating future balances, or for exploring different future scenarios. - - The simplest and most flexible way to do it with hledger is to -manually record a bunch of future-dated transactions. You could keep -these in a separate 'future.journal' and include that with '-f' only -when you want to see them. - -* Menu: - -* --forecast:: -* Inspecting forecast transactions:: -* Forecast reports:: -* Forecast tags:: -* Forecast period in detail:: -* Forecast troubleshooting:: - - -File: hledger.info, Node: --forecast, Next: Inspecting forecast transactions, Up: Forecasting - -18.1 -forecast -============== - -There is another way: with the '--forecast' option, hledger can generate -temporary "forecast transactions" for reporting purposes, according to -periodic transaction rules defined in the journal. Each rule can -generate multiple recurring transactions, so by changing one rule you -can change many forecasted transactions. - - Forecast transactions usually start after ordinary transactions end. -By default, they begin after your latest-dated ordinary transaction, or -today, whichever is later, and they end six months from today. (The -exact rules are a little more complicated, and are given below.) - - This is the "forecast period", which need not be the same as the -report period. You can override it - eg to forecast farther into the -future, or to force forecast transactions to overlap your ordinary -transactions - by giving the -forecast option a period expression -argument, like '--forecast=..2099' or '--forecast=2023-02-15..'. Note -that the '=' is required. - - -File: hledger.info, Node: Inspecting forecast transactions, Next: Forecast reports, Prev: --forecast, Up: Forecasting - -18.2 Inspecting forecast transactions -===================================== - -'print' is the best command for inspecting and troubleshooting forecast -transactions. Eg: - -~ monthly from 2022-12-20 rent - assets:bank:checking - expenses:rent $1000 - -$ hledger print --forecast --today=2023/4/21 -2023-05-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - -2023-06-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - -2023-07-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - -2023-08-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - -2023-09-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - - Here there are no ordinary transactions, so the forecasted -transactions begin on the first occurrence after today's date. (You -won't normally use '--today'; it's just to make these examples -reproducible.) - - -File: hledger.info, Node: Forecast reports, Next: Forecast tags, Prev: Inspecting forecast transactions, Up: Forecasting - -18.3 Forecast reports -===================== - -Forecast transactions affect all reports, as you would expect. Eg: - -$ hledger areg rent --forecast --today=2023/4/21 -Transactions in expenses:rent and subaccounts: -2023-05-20 rent as:ba:checking $1000 $1000 -2023-06-20 rent as:ba:checking $1000 $2000 -2023-07-20 rent as:ba:checking $1000 $3000 -2023-08-20 rent as:ba:checking $1000 $4000 -2023-09-20 rent as:ba:checking $1000 $5000 - -$ hledger bal -M expenses --forecast --today=2023/4/21 -Balance changes in 2023-05-01..2023-09-30: - - || May Jun Jul Aug Sep -===============++=================================== - expenses:rent || $1000 $1000 $1000 $1000 $1000 ----------------++----------------------------------- - || $1000 $1000 $1000 $1000 $1000 - - -File: hledger.info, Node: Forecast tags, Next: Forecast period in detail, Prev: Forecast reports, Up: Forecasting - -18.4 Forecast tags -================== - -Forecast transactions generated by -forecast have a hidden tag, -'_generated-transaction'. So if you ever need to match forecast -transactions, you could use 'tag:_generated-transaction' (or just -'tag:generated') in a query. - - For troubleshooting, you can add the '--verbose-tags' flag. Then, -visible 'generated-transaction' tags will be added also, so you can view -them with the 'print' command. Their value indicates which periodic -rule was responsible. - - -File: hledger.info, Node: Forecast period in detail, Next: Forecast troubleshooting, Prev: Forecast tags, Up: Forecasting - -18.5 Forecast period, in detail -=============================== - -Forecast start/end dates are chosen so as to do something useful by -default in almost all situations, while also being flexible. Here are -(with luck) the exact rules, to help with troubleshooting: - - The forecast period starts on: - - * the later of - * the start date in the periodic transaction rule - * the start date in '--forecast''s argument - - * otherwise (if those are not available): the later of - * the report start date specified with '-b'/'-p'/'date:' - * the day after the latest ordinary transaction in the journal - - * otherwise (if none of these are available): today. - - The forecast period ends on: - - * the earlier of - * the end date in the periodic transaction rule - * the end date in '--forecast''s argument - - * otherwise: the report end date specified with '-e'/'-p'/'date:' - * otherwise: 180 days (~6 months) from today. - - -File: hledger.info, Node: Forecast troubleshooting, Prev: Forecast period in detail, Up: Forecasting - -18.6 Forecast troubleshooting -============================= - -When -forecast is not doing what you expect, one of these tips should -help: - - * Remember to use the '--forecast' option. - * Remember to have at least one periodic transaction rule in your - journal. - * Test with 'print --forecast'. - * Check for typos or too-restrictive start/end dates in your periodic - transaction rule. - * Leave at least 2 spaces between the rule's period expression and - description fields. - * Check for future-dated ordinary transactions suppressing forecasted - transactions. - * Try setting explicit report start and/or end dates with '-b', '-e', - '-p' or 'date:' - * Try adding the '-E' flag to encourage display of empty periods/zero - transactions. - * Try setting explicit forecast start and/or end dates with - '--forecast=START..END' - * Consult Forecast period, in detail, above. - * Check inside the engine: add '--debug=2' (eg). - - -File: hledger.info, Node: Budgeting, Next: Amount formatting, Prev: Forecasting, Up: Top - -19 Budgeting -************ - -With the balance command's '--budget' report, each periodic transaction -rule generates recurring budget goals in specified accounts, and goals -and actual performance can be compared. See the balance command's doc -below. - - You can generate budget goals and forecast transactions at the same -time, from the same or different periodic transaction rules: 'hledger -bal -M --budget --forecast ...' - - See also: Budgeting and Forecasting. - - -File: hledger.info, Node: Amount formatting, Next: Cost reporting, Prev: Budgeting, Up: Top - -20 Amount formatting -******************** - -* Menu: - -* Commodity display style:: -* Rounding:: -* Trailing decimal marks:: -* Amount parseability:: - - -File: hledger.info, Node: Commodity display style, Next: Rounding, Up: Amount formatting - -20.1 Commodity display style -============================ - -For the amounts in each commodity, hledger chooses a consistent display -style (symbol placement, decimal mark and digit group marks, number of -decimal digits) to use in most reports. This is inferred as follows: - - First, if there's a 'D' directive declaring a default commodity, that -commodity symbol and amount format is applied to all no-symbol amounts -in the journal. - - Then each commodity's display style is determined from its -'commodity' directive. We recommend always declaring commodities with -'commodity' directives, since they help ensure consistent display styles -and precisions, and bring other benefits such as error checking for -commodity symbols. Here's an example: - -# Set display styles (and decimal marks, for parsing, if there is no decimal-mark directive) -# for the $, EUR, INR and no-symbol commodities: -commodity $1,000.00 -commodity EUR 1.000,00 -commodity INR 9,99,99,999.00 -commodity 1 000 000.9455 - - But for convenience, if a 'commodity' directive is not present, -hledger infers a commodity's display styles from its amounts as they are -written in the journal (excluding cost amounts and amounts in periodic -transaction rules or auto posting rules). It uses - - * the symbol placement and decimal mark of the first amount seen - * the digit group marks of the first amount with digit group marks - * and the maximum number of decimal digits seen across all amounts. - - And as fallback if no applicable amounts are found, it would use a -default style, like '$1000.00' (symbol on the left with no space, period -as decimal mark, and two decimal digits). - - Finally, commodity styles can be overridden by the -'-c/--commodity-style' command line option. - - -File: hledger.info, Node: Rounding, Next: Trailing decimal marks, Prev: Commodity display style, Up: Amount formatting - -20.2 Rounding -============= - -Amounts are stored internally as decimal numbers with up to 255 decimal -places. They are displayed with their original journal precisions by -print and print-like reports, and rounded to their display precision -(the number of decimal digits specified by the commodity display style) -by other reports. When rounding, hledger uses banker's rounding (it -rounds to the nearest even digit). So eg 0.5 displayed with zero -decimal digits appears as "0". - - -File: hledger.info, Node: Trailing decimal marks, Next: Amount parseability, Prev: Rounding, Up: Amount formatting - -20.3 Trailing decimal marks -=========================== - -If you're wondering why your 'print' report sometimes shows trailing -decimal marks, with no decimal digits; it does this when showing amounts -that have digit group marks but no decimal digits, to disambiguate them -and allow them to be re-parsed reliably (see Decimal marks). Eg: - -commodity $1,000.00 - -2023-01-02 - (a) $1000 - -$ hledger print -2023-01-02 - (a) $1,000. - - If this is a problem (eg when exporting to Ledger), you can avoid it -by disabling digit group marks, eg with -c/-commodity (for each affected -commodity): - -$ hledger print -c '$1000.00' -2023-01-02 - (a) $1000 - - or by forcing print to always show decimal digits, with -round: - -$ hledger print -c '$1,000.00' --round=soft -2023-01-02 - (a) $1,000.00 - - -File: hledger.info, Node: Amount parseability, Prev: Trailing decimal marks, Up: Amount formatting - -20.4 Amount parseability -======================== - -More generally, hledger output falls into three rough categories, which -format amounts a little bit differently to suit different consumers: - - *1. "hledger-readable output" - should be readable by hledger (and -by humans)* - - * This is produced by reports that show full journal entries: - 'print', 'import', 'close', 'rewrite' etc. - * It shows amounts with their original journal precisions, which may - not be consistent from one amount to the next. - * It adds a trailing decimal mark when needed to avoid showing - ambiguous amounts. - * It can be parsed reliably (by hledger and ledger2beancount at - least, but perhaps not by Ledger..) - - *2. "human-readable output" - usually for humans* - - * This is produced by all other reports. - * It shows amounts with standard display precisions, which will be - consistent within each commodity. - * It shows ambiguous amounts unmodified. - * It can be parsed reliably in the context of a known report (when - you know decimals are consistently not being shown, you can assume - a single mark is a digit group mark). - - *3. "machine-readable output" - usually for other software* - - * This is produced by all reports when an output format like 'csv', - 'tsv', 'json', or 'sql' is selected. - * It shows amounts as 1 or 2 do, but without digit group marks. - * It can be parsed reliably (if needed, the decimal mark can be - changed with -c/-commodity-style). - - -File: hledger.info, Node: Cost reporting, Next: Value reporting, Prev: Amount formatting, Up: Top - -21 Cost reporting -***************** - -In some transactions - for example a currency conversion, or a purchase -or sale of stock - one commodity is exchanged for another. In these -transactions there is a conversion rate, also called the cost (when -buying) or selling price (when selling). (In hledger docs we just say -"cost" generically for convenience.) With the '-B/--cost' flag, hledger -can show amounts "at cost", converted to the cost's commodity. - -* Menu: - -* Recording costs:: -* Reporting at cost:: -* Equity conversion postings:: -* Inferring equity conversion postings:: -* Combining costs and equity conversion postings:: -* Requirements for detecting equity conversion postings:: -* Infer cost and equity by default ?:: - - -File: hledger.info, Node: Recording costs, Next: Reporting at cost, Up: Cost reporting - -21.1 Recording costs -==================== - -We'll explore several ways of recording transactions involving costs. -These are also summarised at hledger Cookbook > Cost notation. - - Costs can be recorded explicitly in the journal, using the '@ -UNITCOST' or '@@ TOTALCOST' notation described in Journal > Costs: - - *Variant 1* - -2022-01-01 - assets:dollars $-135 - assets:euros €100 @ $1.35 ; $1.35 per euro (unit cost) - - *Variant 2* - -2022-01-01 - assets:dollars $-135 - assets:euros €100 @@ $135 ; $135 total cost - - Typically, writing the unit cost (variant 1) is preferable; it can be -more effort, requiring more attention to decimal digits; but it reveals -the per-unit cost basis, and makes stock sales easier. - - Costs can also be left implicit, and hledger will infer the cost that -is consistent with a balanced transaction: - - *Variant 3* - -2022-01-01 - assets:dollars $-135 - assets:euros €100 - - Here, hledger will attach a '@@ €100' cost to the first amount (you -can see it with 'hledger print -x'). This form looks convenient, but -there are downsides: - - * It sacrifices some error checking. For example, if you - accidentally wrote €10 instead of €100, hledger would not be able - to detect the mistake. - - * It is sensitive to the order of postings - if they were reversed, a - different entry would be inferred and reports would be different. - - * The per-unit cost basis is not easy to read. - - So generally this kind of entry is not recommended. You can make -sure you have none of these by using '-s' (strict mode), or by running -'hledger check balanced'. - - -File: hledger.info, Node: Reporting at cost, Next: Equity conversion postings, Prev: Recording costs, Up: Cost reporting - -21.2 Reporting at cost -====================== - -Now when you add the '-B'/'--cost' flag to reports ("B" is from Ledger's --B/-basis/-cost flag), any amounts which have been annotated with costs -will be converted to their cost's commodity (in the report output). Ie -they will be displayed "at cost" or "at sale price". - - Some things to note: - - * Costs are attached to specific posting amounts in specific - transactions, and once recorded they do not change. This contrasts - with market prices, which are ambient and fluctuating. - - * Conversion to cost is performed before conversion to market value - (described below). - - -File: hledger.info, Node: Equity conversion postings, Next: Inferring equity conversion postings, Prev: Reporting at cost, Up: Cost reporting - -21.3 Equity conversion postings -=============================== - -There is a problem with the entries above - they are not conventional -Double Entry Bookkeeping (DEB) notation, and because of the "magical" -transformation of one commodity into another, they cause an imbalance in -the Accounting Equation. This shows up as a non-zero grand total in -balance reports like 'hledger bse'. - - For most hledger users, this doesn't matter in practice and can -safely be ignored ! But if you'd like to learn more, keep reading. - - Conventional DEB uses an extra pair of equity postings to balance the -transaction. Of course you can do this in hledger as well: - - *Variant 4* - -2022-01-01 - assets:dollars $-135 - assets:euros €100 - equity:conversion $135 - equity:conversion €-100 - - Now the transaction is perfectly balanced according to standard DEB, -and 'hledger bse''s total will not be disrupted. - - And, hledger can still infer the cost for cost reporting, but it's -not done by default - you must add the '--infer-costs' flag like so: - -$ hledger print --infer-costs -2022-01-01 one hundred euros purchased at $1.35 each - assets:dollars $-135 @@ €100 - assets:euros €100 - equity:conversion $135 - equity:conversion €-100 - -$ hledger bal --infer-costs -B - €-100 assets:dollars - €100 assets:euros --------------------- - 0 - - Here are some downsides of this kind of entry: - - * The per-unit cost basis is not easy to read. - - * Instead of '-B' you must remember to type '-B --infer-costs'. - - * '--infer-costs' works only where hledger can identify the two - equity:conversion postings and match them up with the two - non-equity postings. So writing the journal entry in a particular - format becomes more important. More on this below. - - -File: hledger.info, Node: Inferring equity conversion postings, Next: Combining costs and equity conversion postings, Prev: Equity conversion postings, Up: Cost reporting - -21.4 Inferring equity conversion postings -========================================= - -Can we go in the other direction ? Yes, if you have transactions -written with the @/@@ cost notation, hledger can infer the missing -equity postings, if you add the '--infer-equity' flag. Eg: - -2022-01-01 - assets:dollars -$135 - assets:euros €100 @ $1.35 - -$ hledger print --infer-equity -2022-01-01 - assets:dollars $-135 - assets:euros €100 @ $1.35 - equity:conversion:$-€:€ €-100 - equity:conversion:$-€:$ $135.00 - - The equity account names will be "equity:conversion:A-B:A" and -"equity:conversion:A-B:B" where A is the alphabetically first commodity -symbol. You can customise the "equity:conversion" part by declaring an -account with the 'V'/'Conversion' account type. - - Note you will need to add account declarations for these to your -journal, if you use 'check accounts' or 'check --strict'. - - -File: hledger.info, Node: Combining costs and equity conversion postings, Next: Requirements for detecting equity conversion postings, Prev: Inferring equity conversion postings, Up: Cost reporting - -21.5 Combining costs and equity conversion postings -=================================================== - -Finally, you can use both the @/@@ cost notation and equity postings at -the same time. This in theory gives the best of all worlds - preserving -the accounting equation, revealing the per-unit cost basis, and -providing more flexibility in how you write the entry: - - *Variant 5* - -2022-01-01 one hundred euros purchased at $1.35 each - assets:dollars $-135 - equity:conversion $135 - equity:conversion €-100 - assets:euros €100 @ $1.35 - - All the other variants above can (usually) be rewritten to this final -form with: - -$ hledger print -x --infer-costs --infer-equity - - Downsides: - - * The precise format of the journal entry becomes more important. If - hledger can't detect and match up the cost and equity postings, it - will give a transaction balancing error. - - * The add command does not yet accept this kind of entry (#2056). - - * This is the most verbose form. - - -File: hledger.info, Node: Requirements for detecting equity conversion postings, Next: Infer cost and equity by default ?, Prev: Combining costs and equity conversion postings, Up: Cost reporting - -21.6 Requirements for detecting equity conversion postings -========================================================== - -'--infer-costs' has certain requirements (unlike '--infer-equity', which -always works). It will infer costs only in transactions with: - - * Two non-equity postings, in different commodities. Their order is - significant: the cost will be added to the first of them. - - * Two postings to equity conversion accounts, next to one another, - which balance the two non-equity postings. This balancing is - checked to the same precision (number of decimal places) used in - the conversion posting's amount. Equity conversion accounts are: - - * any accounts declared with account type 'V'/'Conversion', or - their subaccounts - * otherwise, accounts named 'equity:conversion', 'equity:trade', - or 'equity:trading', or their subaccounts. - - And multiple such four-posting groups can coexist within a single -transaction. When '--infer-costs' fails, it does not infer a cost in -that transaction, and does not raise an error (ie, it infers costs where -it can). - - Reading variant 5 journal entries, combining cost notation and equity -postings, has all the same requirements. When reading such an entry -fails, hledger raises an "unbalanced transaction" error. - - -File: hledger.info, Node: Infer cost and equity by default ?, Prev: Requirements for detecting equity conversion postings, Up: Cost reporting - -21.7 Infer cost and equity by default ? -======================================= - -Should '--infer-costs' and '--infer-equity' be enabled by default ? Try -using them always, eg with a shell alias: - -alias h="hledger --infer-equity --infer-costs" - - and let us know what problems you find. - - -File: hledger.info, Node: Value reporting, Next: PART 4 COMMANDS, Prev: Cost reporting, Up: Top - -22 Value reporting -****************** - -hledger can also show amounts "at market value", converted to some other -commodity using the market price or conversion rate on a certain date. - - This is controlled by the '--value=TYPE[,COMMODITY]' option. We also -provide simpler '-V' and '-X COMMODITY' aliases for this, which are -often sufficient. The market prices are declared with a special 'P' -directive, and/or they can be inferred from the costs recorded in -transactions, by using the '--infer-market-prices' flag. - -* Menu: - -* -V Value:: -* -X Value in specified commodity:: -* Valuation date:: -* Finding market price:: -* --infer-market-prices market prices from transactions:: -* Valuation commodity:: -* --value Flexible valuation:: -* Valuation examples:: -* Interaction of valuation and queries:: -* Effect of valuation on reports:: - - -File: hledger.info, Node: -V Value, Next: -X Value in specified commodity, Up: Value reporting - -22.1 -V: Value -============== - -The '-V/--market' flag converts amounts to market value in their default -_valuation commodity_, using the market prices in effect on the -_valuation date(s)_, if any. More on these in a minute. - - -File: hledger.info, Node: -X Value in specified commodity, Next: Valuation date, Prev: -V Value, Up: Value reporting - -22.2 -X: Value in specified commodity -===================================== - -The '-X/--exchange=COMM' option is like '-V', except you tell it which -currency you want to convert to, and it tries to convert everything to -that. - - -File: hledger.info, Node: Valuation date, Next: Finding market price, Prev: -X Value in specified commodity, Up: Value reporting - -22.3 Valuation date -=================== - -Market prices can change from day to day. hledger will use the prices -on a particular valuation date (or on more than one date). By default -hledger uses "end" dates for valuation. More specifically: - - * For single period reports (including normal print and register - reports): - * If an explicit report end date is specified, that is used. - * Otherwise the latest transaction date or non-future P - directive date is used. - - * 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. - - -File: hledger.info, Node: Finding market price, Next: --infer-market-prices market prices from transactions, Prev: Valuation date, Up: Value reporting - -22.4 Finding market price -========================= - -To convert a commodity A to its market value in another commodity B, -hledger looks for a suitable market price (exchange rate) as follows, in -this order of preference: - - 1. A _declared market price_ or _inferred market price_: A's latest - market price in B on or before the valuation date as declared by a - P directive, or (with the '--infer-market-prices' flag) inferred - from costs. - - 2. A _reverse market price_: the inverse of a declared or inferred - market price from B to A. - - 3. A _forward chain of market prices_: a synthetic price formed by - combining the shortest chain of "forward" (only 1 above) market - prices, leading from A to B. - - 4. _Any chain of market prices_: a chain of any market prices, - including both forward and reverse prices (1 and 2 above), leading - from A to B. - - There is a limit to the length of these price chains; if hledger -reaches that length without finding a complete chain or exhausting all -possibilities, it will give up (with a "gave up" message visible in -'--debug=2' output). That limit is currently 1000. - - Amounts for which no suitable market price can be found, are not -converted. - - -File: hledger.info, Node: --infer-market-prices market prices from transactions, Next: Valuation commodity, Prev: Finding market price, Up: Value reporting - -22.5 -infer-market-prices: market prices from transactions -========================================================== - -Normally, market value in hledger is fully controlled by, and requires, -P directives in your journal. Since adding and updating those can be a -chore, and since transactions usually take place at close to market -value, why not use the recorded costs as additional market prices (as -Ledger does) ? Adding the '--infer-market-prices' flag to '-V', '-X' or -'--value' enables this. - - So for example, 'hledger bs -V --infer-market-prices' will get market -prices both from P directives and from transactions. If both occur on -the same day, the P directive takes precedence. - - There is a downside: value reports can sometimes be affected in -confusing/undesired ways by your journal entries. If this happens to -you, read all of this Value reporting section carefully, and try adding -'--debug' or '--debug=2' to troubleshoot. - - '--infer-market-prices' can infer market prices from: - - * multicommodity transactions with explicit prices ('@'/'@@') - - * multicommodity transactions with implicit prices (no '@', two - commodities, unbalanced). (With these, the order of postings - matters. 'hledger print -x' can be useful for troubleshooting.) - - * multicommodity transactions with equity postings, if cost is - inferred with '--infer-costs'. - - There is a limitation (bug) currently: when a valuation commodity is -not specified, prices inferred with '--infer-market-prices' do not help -select a default valuation commodity, as 'P' prices would. So -conversion might not happen because no valuation commodity was detected -('--debug=2' will show this). To be safe, specify the valuation -commmodity, eg: - - * '-X EUR --infer-market-prices', not '-V --infer-market-prices' - * '--value=then,EUR --infer-market-prices', not '--value=then - --infer-market-prices' - - Signed costs and market prices can be confusing. For reference, here -is the current behaviour, since hledger 1.25. (If you think it should -work differently, see #1870.) - -2022-01-01 Positive Unit prices - a A 1 - b B -1 @ A 1 - -2022-01-01 Positive Total prices - a A 1 - b B -1 @@ A 1 - - -2022-01-02 Negative unit prices - a A 1 - b B 1 @ A -1 - -2022-01-02 Negative total prices - a A 1 - b B 1 @@ A -1 - - -2022-01-03 Double Negative unit prices - a A -1 - b B -1 @ A -1 - -2022-01-03 Double Negative total prices - a A -1 - b B -1 @@ A -1 - - All of the transactions above are considered balanced (and on each -day, the two transactions are considered equivalent). Here are the -market prices inferred for B: - -$ hledger -f- --infer-market-prices prices -P 2022-01-01 B A 1 -P 2022-01-01 B A 1.0 -P 2022-01-02 B A -1 -P 2022-01-02 B A -1.0 -P 2022-01-03 B A -1 -P 2022-01-03 B A -1.0 - - -File: hledger.info, Node: Valuation commodity, Next: --value Flexible valuation, Prev: --infer-market-prices market prices from transactions, Up: Value reporting - -22.6 Valuation commodity -======================== - -*When you specify a valuation commodity ('-X COMM' or '--value -TYPE,COMM'):* -hledger will convert all amounts to COMM, wherever it can find a -suitable market price (including by reversing or chaining prices). - - *When you leave the valuation commodity unspecified ('-V' or '--value -TYPE'):* -For each commodity A, hledger picks a default valuation commodity as -follows, in this order of preference: - - 1. The price commodity from the latest P-declared market price for A - on or before valuation date. - - 2. The price commodity from the latest P-declared market price for A - on any date. (Allows conversion to proceed when there are inferred - prices before the valuation date.) - - 3. If there are no P directives at all (any commodity or date) and the - '--infer-market-prices' flag is used: the price commodity from the - latest transaction-inferred price for A on or before valuation - date. - - This means: - - * If you have P directives, they determine which commodities '-V' - will convert, and to what. - - * If you have no P directives, and use the '--infer-market-prices' - flag, costs determine it. - - Amounts for which no valuation commodity can be found are not -converted. - - -File: hledger.info, Node: --value Flexible valuation, Next: Valuation examples, Prev: Valuation commodity, Up: Value reporting - -22.7 -value: Flexible valuation -=============================== - -'-V' and '-X' are special cases of the more general '--value' option: - - --value=TYPE[,COMM] TYPE is then, end, now or YYYY-MM-DD. - COMM is an optional commodity symbol. - Shows amounts converted to: - - default valuation commodity (or COMM) using market prices at posting dates - - default valuation commodity (or COMM) using market prices at period end(s) - - default valuation commodity (or COMM) using current market prices - - default valuation commodity (or COMM) using market prices at some date - - The TYPE part selects cost or value and valuation date: - -'--value=then' - - Convert amounts to their value in the default valuation commodity, - using market prices on each posting's date. -'--value=end' - - Convert amounts to their value in the default valuation commodity, - using market prices on the last day of the report period (or if - unspecified, the journal's end date); or in multiperiod reports, - market prices on the last day of each subperiod. -'--value=now' - - Convert amounts to their value in the default valuation commodity - using current market prices (as of when report is generated). -'--value=YYYY-MM-DD' - - Convert amounts to their value in the default valuation commodity - using market prices on this date. - - To select a different valuation commodity, add the optional ',COMM' -part: a comma, then the target commodity's symbol. Eg: -*'--value=now,EUR'*. hledger will do its best to convert amounts to -this commodity, deducing market prices as described above. - - -File: hledger.info, Node: Valuation examples, Next: Interaction of valuation and queries, Prev: --value Flexible valuation, Up: Value reporting - -22.8 Valuation examples -======================= - -Here are some quick examples of '-V': - -; one euro is worth this many dollars from nov 1 -P 2016/11/01 € $1.10 - -; purchase some euros on nov 3 -2016/11/3 - assets:euros €100 - assets:checking - -; the euro is worth fewer dollars by dec 21 -P 2016/12/21 € $1.03 - - How many euros do I have ? - -$ hledger -f t.j bal -N euros - €100 assets:euros - - What are they worth at end of nov 3 ? - -$ hledger -f t.j bal -N euros -V -e 2016/11/4 - $110.00 assets:euros - - What are they worth after 2016/12/21 ? (no report end date -specified, defaults to today) - -$ hledger -f t.j bal -N euros -V - $103.00 assets:euros - - Here are some examples showing the effect of '--value', as seen with -'print': - -P 2000-01-01 A 1 B -P 2000-02-01 A 2 B -P 2000-03-01 A 3 B -P 2000-04-01 A 4 B - -2000-01-01 - (a) 1 A @ 5 B - -2000-02-01 - (a) 1 A @ 6 B - -2000-03-01 - (a) 1 A @ 7 B - - Show the cost of each posting: - -$ hledger -f- print --cost -2000-01-01 - (a) 5 B - -2000-02-01 - (a) 6 B - -2000-03-01 - (a) 7 B - - Show the value as of the last day of the report period (2000-02-29): - -$ hledger -f- print --value=end date:2000/01-2000/03 -2000-01-01 - (a) 2 B - -2000-02-01 - (a) 2 B - - With no report period specified, the latest transaction date or price -date is used as valuation date (2000-04-01): - -$ hledger -f- print --value=end -2000-01-01 - (a) 3 B - -2000-02-01 - (a) 3 B - -2000-03-01 - (a) 3 B - - The value today is the same (the 2000-04-01 price is still in -effect): - -$ hledger -f- print --value=now -2000-01-01 - (a) 4 B - -2000-02-01 - (a) 4 B - -2000-03-01 - (a) 4 B - - Show the value on 2000/01/15: - -$ hledger -f- print --value=2000-01-15 -2000-01-01 - (a) 1 B - -2000-02-01 - (a) 1 B - -2000-03-01 - (a) 1 B - - -File: hledger.info, Node: Interaction of valuation and queries, Next: Effect of valuation on reports, Prev: Valuation examples, Up: Value reporting - -22.9 Interaction of valuation and queries -========================================= - -When matching postings based on queries in the presence of valuation, -the following happens: - - 1. The query is separated into two parts: - 1. the currency ('cur:') or amount ('amt:'). - 2. all other parts. - - 2. The postings are matched to the currency and amount queries based - on pre-valued amounts. - 3. Valuation is applied to the postings. - 4. The postings are matched to the other parts of the query based on - post-valued amounts. - - Related: #1625 - - -File: hledger.info, Node: Effect of valuation on reports, Prev: Interaction of valuation and queries, Up: Value reporting - -22.10 Effect of valuation on reports -==================================== - -Here is a reference for how valuation is supposed to affect each part of -hledger's reports. It may be useful when troubleshooting. If you find -problems, please report them, ideally with a reproducible example. -Related: #329, #1083. - - First, a quick glossary: - -_cost_ - - calculated using price(s) recorded in the transaction(s). -_value_ - - market value using available market price declarations, or the - unchanged amount if no conversion rate can be found. -_report start_ - - the first day of the report period specified with -b or -p or - date:, otherwise today. -_report or journal start_ - - the first day of the report period specified with -b or -p or - date:, otherwise the earliest transaction date in the journal, - otherwise today. -_report end_ - - the last day of the report period specified with -e or -p or date:, - otherwise today. -_report or journal end_ - - the last day of the report period specified with -e or -p or date:, - otherwise the latest transaction date in the journal, otherwise - today. -_report interval_ - - a flag (-D/-W/-M/-Q/-Y) or period expression that activates the - report's multi-period mode (whether showing one or many - subperiods). - -Report '-B', '-V', '-X' '--value=then' '--value=end''--value=DATE', -type '--cost' '--value=now' ------------------------------------------------------------------------------- -*print* -posting cost value at value at posting value at value -amounts report end date report or at - or today journal DATE/today - end -balance unchanged unchanged unchanged unchanged unchanged -assertions/assignments -*register* -starting cost value at valued at day value at value -balance report or each historical report or at -(-H) journal posting was made journal DATE/today - end end -starting cost value at valued at day value at value -balance day before each historical day before at -(-H) report or posting was made report or DATE/today -with journal journal -report start start -interval -posting cost value at value at posting value at value -amounts report or date report or at - journal journal DATE/today - end end -summary summarised value at sum of postings value at value -posting cost period in interval, period at -amounts ends valued at ends DATE/today -with interval start -report -interval -running sum/average sum/average sum/average of sum/average sum/average -total/averageof of displayed values of of - displayed displayed displayed displayed - values values values values -*balance -(bs, -bse, cf, -is)* -balance sums of value at value at posting value at value -changes costs report end date report or at - or today journal DATE/today - of sums of end of of - postings sums of sums - postings of - postings -budget like like like balance like like -amounts balance balance changes balances balance -(-budget) changes changes changes -grand sum of sum of sum of displayed sum of sum of -total displayed displayed valued displayed displayed - values values values values -*balance -(bs, -bse, cf, -is) with -report -interval* -starting sums of value at sums of values value at sums -balances costs of report of postings report of -(-H) postings start of before report start of postings - before sums of start at sums of before - report all respective all report - start postings posting dates postings start - before before - report report - start start -balance sums of same as sums of values balance value -changes costs of -value=end of postings in change in at -(bal, postings period at each DATE/today -is, bs in period respective period, of --change, posting dates valued at sums -cf period of --change) ends postings -end sums of same as sums of values period end value -balances costs of -value=end of postings from balances, at -(bal -H, postings before period valued at DATE/today -is -H, from start to period period of -bs, cf) before end at ends sums - report respective of - start to posting dates postings - period end -budget like like like balance like like -amounts balance balance changes/end balances balance -(-budget) changes/end changes/end balances changes/end - balances balances balances -row sums, sums, sums, averages sums, sums, -totals, averages averages of displayed averages averages -row of of values of of -averages displayed displayed displayed displayed -(-T, -A) values values values values -column sums of sums of sums of sums of sums -totals displayed displayed displayed values displayed of - values values values displayed - values -grand sum, sum, sum, average of sum, sum, -total, average of average of column totals average of average -grand column column column of -average totals totals totals column - totals - - '--cumulative' is omitted to save space, it works like '-H' but with -a zero starting balance. - - -File: hledger.info, Node: PART 4 COMMANDS, Next: Help commands, Prev: Value reporting, Up: Top - -23 PART 4: COMMANDS -******************* - -Here are hledger's standard subcommands. You can list these by running -'hledger'. If you have installed more add-on commands, they also will -be listed. - - In the following command docs, each command's specific options are -shown. Most commands also support the general options described above, -though some of them might have no effect. (Usually if there's a -sensible way for a general option to affect a command, it will.) You -can list all of a command's options by running 'hledger CMD -h'. - - *Help commands* - - * commands - show the hledger commands list (default) - * demo - show small hledger demos in the terminal - * help - show the hledger manual with info, man, or pager - - *User interface commands* - - * repl - run commands from an interactive prompt - * run - run commands from a script - * ui - (if installed) run hledger's terminal UI - * web - (if installed) run hledger's web UI - - *Data entry commands* - - * add - add transactions using terminal prompts - * import - add new transactions from other files, eg CSV files - - *Basic report commands* - - * accounts - show account names - * codes - show transaction codes - * commodities - show commodity/currency symbols - * descriptions - show transaction descriptions - * files - show input file paths - * notes - show note parts of transaction descriptions - * payees - show payee parts of transaction descriptions - * prices - show market prices - * stats - show journal statistics - * tags - show tag names - - *Standard report commands* - - * print - show transactions or export journal data - * aregister (areg) - show transactions in a particular account - * register (reg) - show postings in one or more accounts & running - total - * balancesheet (bs) - show assets, liabilities and net worth - * balancesheetequity (bse) - show assets, liabilities and equity - * cashflow (cf) - show changes in liquid assets - * incomestatement (is) - show revenues and expenses - - *Advanced report commands* - - * balance (bal) - show balance changes, end balances, budgets, - gains.. - * roi - show return on investments - - *Chart commands* - - * activity - show bar charts of posting counts per period - - *Data generation commands* - - * close - generate balance-zeroing/restoring transactions - * rewrite - generate auto postings, like print -auto - - *Maintenance commands* - - * check - check for various kinds of error in the data - * diff - compare account transactions in two journal files - * setup - check and show the status of the hledger installation - * test - run self tests - - Next, these commands are described in detail. - - -File: hledger.info, Node: Help commands, Next: User interface commands, Prev: PART 4 COMMANDS, Up: Top - -24 Help commands -**************** - -* Menu: - -* commands:: -* demo:: -* help:: - - -File: hledger.info, Node: commands, Next: demo, Up: Help commands - -24.1 commands -============= - -Show the hledger commands list. - -Flags: - --builtin show only builtin commands, not addons - - -File: hledger.info, Node: demo, Next: help, Prev: commands, Up: Help commands - -24.2 demo -========= - -Play demos of hledger usage in the terminal, if asciinema is installed. - -Flags: - -s --speed=SPEED playback speed (1 is original speed, .5 is half, 2 - is double, etc (default: 2)) - - Run this command with no argument to list the demos. To play a demo, -write its number or a prefix or substring of its title. Tips: - - Make your terminal window large enough to see the demo clearly. - - Use the -s/-speed SPEED option to set your preferred playback speed, -eg '-s4' to play at 4x original speed or '-s.5' to play at half speed. -The default speed is 2x. - - During playback, several keys are available: SPACE to pause/unpause, -. to step forward (while paused), CTRL-c quit. - - Examples: - -$ hledger demo # list available demos -$ hledger demo 1 # play the first demo at default speed (2x) -$ hledger demo install -s4 # play the "install" demo at 4x speed - - This command is experimental: there aren't many useful demos yet. - - -File: hledger.info, Node: help, Prev: demo, Up: Help commands - -24.3 help -========= - -Show the hledger user manual with 'info', 'man', or a pager. With a -(case insensitive) TOPIC argument, try to open it at that section -heading. - -Flags: - -i show the manual with info - -m show the manual with man - -p show the manual with $PAGER or less - (less is always used if TOPIC is specified) - - This command shows the hledger manual built in to your hledger -executable. It can be useful when offline, or when you prefer the -terminal to a web browser, or when the appropriate hledger manual or -viewers are not installed properly on your system. - - By default it chooses the best viewer found in $PATH, trying in this -order: 'info', 'man', '$PAGER', 'less', 'more', stdout. (If a TOPIC is -specified, '$PAGER' and 'more' are not tried.) You can force the use of -info, man, or a pager with the '-i', '-m', or '-p' flags. If no viewer -can be found, or if running non-interactively, it just prints the manual -to stdout. - - When using 'info', TOPIC can match either the full heading or a -prefix. If your 'info --version' is < 6, you'll need to upgrade it, eg -with ''brew install texinfo'' on mac. - - When using 'man' or 'less', TOPIC must match the full heading. For a -prefix match, you can write ''TOPIC.*''. - - Examples - -$ hledger help -h # show the help command's usage -$ hledger help # show the manual with info, man or $PAGER -$ hledger help 'time periods' # show the manual's "Time periods" topic -$ hledger help 'time periods' -m # use man, even if info is installed - - -File: hledger.info, Node: User interface commands, Next: Data entry commands, Prev: Help commands, Up: Top - -25 User interface commands -************************** - -* Menu: - -* repl:: -* run:: -* ui:: -* web:: - - -File: hledger.info, Node: repl, Next: run, Up: User interface commands - -25.1 repl -========= - -Start an interactive prompt, where you can run any of hledger's -commands. Data files are parsed just once, so the commands run faster. - -Flags: -no command-specific flags - - This command is experimental and could change in the future. - - 'hledger repl' starts a read-eval-print loop (REPL) where you can -enter commands interactively. As with the 'run' command, each input -file (or each input file/input options combination) is parsed just once, -so commands will run more quickly than if you ran them individually at -the command line. - - Also like 'run', the input file(s) specified for the 'repl' command -will be the default input for all interactive commands. You can -override this temporarily by specifying an '-f' option in particular -commands. But note that commands will not see any changes made to input -files (eg by 'add') until you exit and restart the REPL. - - The command syntax is the same as with 'run': - - * enter one hledger command at a time, without the usual 'hledger' - first word - * empty lines and comment text from '#' to end of line are ignored - * use single or double quotes to quote arguments when needed - * type 'exit' or 'quit' or control-D to exit the REPL. - - While it is running, the REPL remembers your command history, and you -can navigate in the usual ways: - - * Keypad or Emacs navigation keys to edit the current command line - * UP/DOWN or control-P/control-N to step back/forward through history - * control-R to search for a past command - * TAB to complete file paths. - - Generally 'repl' command lines should feel much like the normal -hledger CLI, but you may find differences. 'repl' is a little stricter; -eg it requires full command names or official abbreviations (as seen in -the commands list). - - The 'commands' and 'help' commands, and the command help flags ('CMD ---tldr', 'CMD -h/--help', 'CMD --info', 'CMD --man'), can be useful. - - You can type control-C to cancel a long-running command (but only -once; typing it a second time will exit the REPL). - - And in most shells you can type control-Z to temporarily exit to the -shell (and then 'fg' to return to the REPL). - -* Menu: - -* Examples:: - - -File: hledger.info, Node: Examples, Up: repl - -25.1.1 Examples ---------------- - -Start the REPL and enter some commands: - -$ hledger repl -Enter hledger commands. To exit, enter 'quit' or 'exit', or send EOF. -% stats -Main file : .../2025.journal -... -% stats -f 2024/2024.journal -Main file : .../2024.journal -... -% stats -Main file : .../2025.journal -... - - or: - -$ hledger repl -f some.journal -Enter hledger commands. To exit, enter 'quit' or 'exit', or send EOF. -% bs -... -% print -b 'last week' -... -% bs -f other.journal -... - - -File: hledger.info, Node: run, Next: ui, Prev: repl, Up: User interface commands - -25.2 run -======== - -Run a sequence of hledger commands, provided as files or command line -arguments. Data files are parsed just once, so the commands run faster. - -Flags: -no command-specific flags - - This command is experimental and could change in the future. - - You can use 'run' in three ways: - - * 'hledger run -- CMD1 -- CMD2 -- CMD3' - read commands from the - command line, separated by '--' - * 'hledger run SCRIPTFILE1 SCRIPTFILE2' - read commands from one or - more files - * 'cat SCRIPTFILE1 | hledger run' - read commands from standard - input. - - 'run' first loads the input file(s) specified by 'LEDGER_FILE' or by -'-f' options, in the usual way. Then it runs each command in turn, each -using the same input data. But if you want a particular command to use -different input, you can specify an '-f' option within that command. -This will override (not add to) the default input, just for that -command. - - Each input file (more precisely, each combination of input file and -input options) is parsed only once. This means that commands will not -see any changes made to these files, until the next run. But the -commands will run more quickly than if run individually (typically about -twice as fast). - - Command scripts, whether in a file or written on the command line, -have a simple syntax: - - * each line may contain a single hledger command and its arguments, - without the usual 'hledger' first word - * empty lines are ignored - * text from '#' to end of line is a comment, and ignored - * you can use single or double quotes to quote arguments when needed, - as on the command line - * these extra commands are available: 'echo TEXT' prints some text, - and 'exit' or 'quit' ends the run. - - On unix systems you can use '#!/usr/bin/env hledger run' in the first -line of a command file to make it a runnable script. If that gives an -error, use '#!/usr/bin/env -S hledger run'. - - It's ok to use the 'run' command recursively within a command script. - - You may find some differences in behaviour between 'run' command -lines and normal hledger command lines. 'run' is a little stricter; eg -it requires full command names or official abbreviations (as seen in the -commands list), and command options must be written after the command -name. - -* Menu: - -* Examples: Examples 2. - - -File: hledger.info, Node: Examples 2, Up: run - -25.2.1 Examples ---------------- - -Run commands from the command line: - -hledger -f some.journal run -- balance assets --depth 2 -- balance liabilities -f /some/other.journal --depth 3 --transpose -- stats - - This would load 'some.journal', run 'balance assets --depth 2' on it, -then run 'balance liabilities --depth 3 --transpose' on -'/some/other.journal', and finally run 'stats' on 'some.journal' - - Run commands from standard input: - -(echo "files"; echo "stats") | hledger -f some.journal run - - Run commands as a script: - -$ cat report -#!/usr/bin/env -S hledger run -f some.journal - -echo "List of accounts in some.journal" -accounts - -echo "Assets of some.journal" -balance assets --depth 2 - -echo "Liabilities from /some/other.journal" -balance liabilities -f /some/other.journal --depth 3 --transpose - -echo "Commands from another.script, applied to another.journal" -run -f another.journal another.script - -$ chmod +x report -$ ./report -List of accounts in some.journal -... - - -File: hledger.info, Node: ui, Next: web, Prev: run, Up: User interface commands - -25.3 ui -======= - -Runs hledger-ui (if installed). - - -File: hledger.info, Node: web, Prev: ui, Up: User interface commands - -25.4 web -======== - -Runs hledger-web (if installed). - - -File: hledger.info, Node: Data entry commands, Next: Basic report commands, Prev: User interface commands, Up: Top - -26 Data entry commands -********************** - -* Menu: - -* add:: -* add and balance assertions:: -* add and balance assignments:: -* import:: - - -File: hledger.info, Node: add, Next: add and balance assertions, Up: Data entry commands - -26.1 add -======== - -Add new transactions to a journal file, with interactive prompting. - -Flags: - --no-new-accounts don't allow creating new accounts - - Many hledger users edit their journals directly with a text editor, -or generate them from CSV. For more interactive data entry, there is the -'add' command, which prompts interactively on the console for new -transactions, and appends them to the main journal file (which should be -in journal format). Existing transactions are not changed. This is one -of the few hledger commands that writes to the journal file (see also -'import'). - - To use it, just run 'hledger add' and follow the prompts. You can -add as many transactions as you like; when you are finished, enter '.' -or press control-d or control-c to exit. - - Features: - - * add tries to provide useful defaults, using the most similar (by - description) recent transaction (filtered by the query, if any) as - a template. - * You can also set the initial defaults with command line arguments. - * Readline-style edit keys can be used during data entry. - * The tab key will auto-complete whenever possible - accounts, - payees/descriptions, dates ('yesterday', 'today', 'tomorrow'). If - the input area is empty, it will insert the default value. - * A parenthesised transaction code may be entered following a date. - * Comments and tags may be entered following a description or amount. - * If you make a mistake, enter '<' at any prompt to go one step - backward. - * Input prompts are displayed in a different colour when the terminal - supports it. - - Notes: - - * If you enter a number with no commodity symbol, and you have - declared a default commodity with a 'D' directive, you might expect - 'add' to add this symbol for you. It does not do this; we assume - that if you are using a 'D' directive you prefer not to see the - commodity symbol repeated on amounts in the journal. - * 'add' creates entries in journal format; it won't work with - timeclock or timedot files. - - Examples: - - * Record new transactions, saving to the default journal file: - - 'hledger add' - - * Add transactions to 2024.journal, but also load 2023.journal for - completions: - - 'hledger add --file 2024.journal --file 2023.journal' - - * Provide answers for the first four prompts: - - 'hledger add today 'best buy' expenses:supplies '$20'' - - There is a detailed tutorial at https://hledger.org/add.html. - - -File: hledger.info, Node: add and balance assertions, Next: add and balance assignments, Prev: add, Up: Data entry commands - -26.2 add and balance assertions -=============================== - -Since hledger 1.43, whenever you enter a posting amount, 'add' will -re-check all balance assertions in the journal, and if any of them fail, -it will report the problem and ask for the amount again. - - You can also add a new balance assertion, following the amount as in -journal format. - - The new transaction's date, and the new posting's posting date if any -(entered in a comment following the amount), will influence assertion -checking. - - You can use '-I'/'--ignore-assertions' to disable assertion checking -temporarily. - - -File: hledger.info, Node: add and balance assignments, Next: import, Prev: add and balance assertions, Up: Data entry commands - -26.3 add and balance assignments -================================ - -Balance assignments are not recalculated during a 'hledger add' session. -When 'add' runs, it sees the journal with all balance assignments -already processed and converted to assertions. So if you add a new -posting which is dated earlier than a balance assignment, it will break -the assertion and be rejected. You can make it work by using 'hledger -add -I'. - - -File: hledger.info, Node: import, Prev: add and balance assignments, Up: Data entry commands - -26.4 import -=========== - -Import new transactions from one or more data files to the main journal. - -Flags: - --catchup just mark all transactions as already imported - --dry-run just show the transactions to be imported - - This command detects new transactions in one or more data files -specified as arguments, and appends them to the main journal. - - You can import from any input file format hledger supports, but -CSV/SSV/TSV files, downloaded from financial institutions, are the most -common import source. - - The import destination is the default journal file, or another -specified in the usual way with '$LEDGER_FILE' or '-f/--file'. It -should be in journal format. - - Examples: - -$ hledger import bank1-checking.csv bank1-savings.csv - -$ hledger import *.csv - -* Menu: - -* Import dry run:: -* Overlap detection:: -* First import:: -* Importing balance assignments:: -* Import and commodity styles:: -* Import archiving:: -* Import special cases:: - - -File: hledger.info, Node: Import dry run, Next: Overlap detection, Up: import - -26.4.1 Import dry run ---------------------- - -It's useful to preview the import by running first with '--dry-run', to -sanity check the range of dates being imported, and to check the effect -of your conversion rules if converting from CSV. Eg: - -$ hledger import bank.csv --dry-run - - The dry run output is valid journal format, so hledger can re-parse -it. If the output is large, you could show just the uncategorised -transactions like so: - -$ hledger import --dry-run bank.csv | hledger -f- -I print unknown - - You could also run this repeatedly to see the effect of edits to your -conversion rules: - -$ watchexec -- "hledger import --dry-run bank.csv | hledger -f- -I print unknown" - - Once the conversion and dates look good enough to import to your -journal, perhaps with some manual fixups to follow, you would do the -actual import: - -$ hledger import bank.csv - - -File: hledger.info, Node: Overlap detection, Next: First import, Prev: Import dry run, Up: import - -26.4.2 Overlap detection ------------------------- - -Reading CSV files is built in to hledger, and not specific to 'import'; -so you could also import by doing 'hledger -f bank.csv print ->>$LEDGER_FILE'. - - But 'import' is easier and provides some advantages. The main one is -that it avoids re-importing transactions it has seen on previous runs. -This means you don't have to worry about overlapping data in successive -downloads of your bank CSV; just download and 'import' as often as you -like, and only the new transactions will be imported each time. - - We don't call this "deduplication", as it's generally not possible to -reliably detect duplicates in bank CSV. Instead, 'import' remembers the -latest date processed previously in each CSV file (saving it in a hidden -file), and skips any records prior to that date. This works well for -most real-world CSV, where: - - 1. the data file name is stable (does not change) across imports - 2. the item dates are stable across imports - 3. the order of same-date items is stable across imports - 4. the newest items have the newest dates - - (Occasional violations of 2-4 are often harmless; you can reduce the -chance of disruption by downloading and importing more often.) - - Overlap detection is automatic, and shouldn't require much attention -from you, except perhaps at first import (see below). But here's how it -works: - - * For each 'FILE' being imported from: - - 1. hledger reads a file named '.latest.FILE' file in the same - directory, if any. This file contains the latest record date - previously imported from FILE, in YYYY-MM-DD format. If - multiple records with that date were imported, the date is - repeated on N lines. - - 2. hledger reads records from FILE. If a latest date was found in - step 1, any records before that date, and the first N records - on that date, are skipped. - - * After a successful import from all FILEs, without error and without - '--dry-run', hledger updates each FILE's '.latest.FILE' for next - time. - - If this goes wrong, it's relatively easy to repair: - - * You'll notice it before import when you preview with 'import - --dry-run'. - * Or after import when you try to reconcile your hledger account - balances with your bank. - * 'hledger print -f FILE.csv' will show all recently downloaded - transactions. Compare these with your journal. Copy/paste if - needed. - * Update your conversion rules and print again, if needed. - * You can manually update or remove the .latest file, or use 'import - --catchup FILE'. - * Download and import more often, eg twice a week, at least while you - are learning. It's easier to review and troubleshoot when there - are fewer transactions. - - -File: hledger.info, Node: First import, Next: Importing balance assignments, Prev: Overlap detection, Up: import - -26.4.3 First import -------------------- - -The first time you import from a file, when no corresponding .latest -file has been created yet, all of the records will be imported. - - But perhaps you have been entering the data manually, so you know -that all of these transactions are already recorded in the journal. In -this case you can run 'hledger import --catchup' once. This will create -a .latest file containing the latest CSV record date, so that none of -those records will be re-imported. - - Or, if you know that some but not all of the transactions are in the -journal, you can create the .latest file yourself. Eg, let's say you -previously recorded foobank transactions up to 2024-10-31 in the -journal. Then in the directory where you'll be saving 'foobank.csv', -you would create a '.latest.foobank.csv' file containing - -2024-10-31 - - Or if you had three foobank transactions recorded with that date, you -would repeat the date that many times: - -2024-10-31 -2024-10-31 -2024-10-31 - - Then 'hledger import foobank.csv [--dry-run]' will import only the -newer records. - - -File: hledger.info, Node: Importing balance assignments, Next: Import and commodity styles, Prev: First import, Up: import - -26.4.4 Importing balance assignments ------------------------------------- - -Journal entries added by import will have all posting amounts made -explicit (like 'print -x'). - - This means that any balance assignments in the imported entries would -need to be evaluated. But this generally isn't possible, as the main -file's account balances are not visible during import. So try to avoid -generating balance assignments with your CSV rules, or importing from a -journal that contains balance assignments. (Balance assignments are -best avoided anyway.) - - But if you must use them, eg because your CSV includes only balances: -you can import with 'print', which leaves implicit amounts implicit. -('print' can also do overlap detection like import, with the '--new' -flag): - -$ hledger print --new -f bank.csv >> $LEDGER_FILE - - (If you think 'import' should preserve implicit balances, please test -that and send a pull request.) - - -File: hledger.info, Node: Import and commodity styles, Next: Import archiving, Prev: Importing balance assignments, Up: import - -26.4.5 Import and commodity styles ----------------------------------- - -Amounts in entries added by import will be formatted according to the -journal's canonical commodity styles, as declared by 'commodity' -directives or inferred from the journal's amounts. - - Related: CSV > Amount decimal places. - - -File: hledger.info, Node: Import archiving, Next: Import special cases, Prev: Import and commodity styles, Up: import - -26.4.6 Import archiving ------------------------ - -When importing from a CSV rules file ('hledger import bank.rules'), you -can use the archive rule to enable automatic archiving of the data file. -After a successful import, the data file (specified by 'source') will be -moved to an archive folder ('data/', next to the rules file, -auto-created), and renamed similar to the rules file, with a date. This -can be useful for troubleshooting, detecting variations in your banks' -CSV data, regenerating entries with improved rules, etc. - - The 'archive' rule also causes 'import' to handle 'source' glob -patterns differently: when there are multiple matched files, it will -pick the oldest, not the newest. - - -File: hledger.info, Node: Import special cases, Prev: Import archiving, Up: import - -26.4.7 Import special cases ---------------------------- - -* Menu: - -* Deduplication:: -* Varying file name:: -* Multiple versions:: - - -File: hledger.info, Node: Deduplication, Next: Varying file name, Up: Import special cases - -26.4.7.1 Deduplication -...................... - -Here are two kinds of "deduplication" which 'import' does not handle -(and should not, because these can happen legitimately in financial -data): - - * Two or more of the new CSV records are identical, and generate - identical new journal entries. - * A new CSV record generates a journal entry identical to one(s) - already in the journal. - - -File: hledger.info, Node: Varying file name, Next: Multiple versions, Prev: Deduplication, Up: Import special cases - -26.4.7.2 Varying file name -.......................... - -If you have a download whose file name varies, you could rename it to a -fixed name after each download. Or you could use a CSV 'source' rule -with a suitable glob pattern, and import from the .rules file. - - -File: hledger.info, Node: Multiple versions, Prev: Varying file name, Up: Import special cases - -26.4.7.3 Multiple versions -.......................... - -Say you download 'bank.csv', import it, but forget to delete it from -your downloads folder. The next time you download it, your web browser -will save it as (eg) 'bank (2).csv'. The source rule's glob patterns -are for just this situation: instead of specifying 'source bank.csv', -specify 'source bank*.csv'. Then 'hledger -f bank.rules CMD' or -'hledger import bank.rules' will automatically pick the newest matched -file ('bank (2).csv'). - - Alternately, what if you download, but forget to import or delete, -then download again ? Now each of 'bank.csv' and 'bank (2).csv' might -contain data that's not in the other, and not in your journal. In this -case, it's best to import each of them in turn, oldest first (otherwise, -overlap detection could cause new records to be skipped). Enabling -import archiving ensures this. Then 'hledger import bank.rules; hledger -import bank.rules' will import and archive first 'bank.csv', then 'bank -(2).csv'. - - -File: hledger.info, Node: Basic report commands, Next: Standard report commands, Prev: Data entry commands, Up: Top - -27 Basic report commands -************************ - -* Menu: - -* accounts:: -* codes:: -* commodities:: -* descriptions:: -* files:: -* notes:: -* payees:: -* prices:: -* stats:: -* tags:: - - -File: hledger.info, Node: accounts, Next: codes, Up: Basic report commands - -27.1 accounts -============= - -List the account names used or declared in the journal. - -Flags: - -u --used list accounts used - -d --declared list accounts declared - --undeclared list accounts used but not declared - --unused list accounts declared but not used - --find list the first account matched by the first - argument (a case-insensitive infix regexp) - --types also show account types when known - --positions also show where accounts were declared - --directives show as account directives, for use in journals - -l --flat list/tree mode: show accounts as a flat list - (default) - -t --tree list/tree mode: show accounts as a tree - --drop=N flat mode: omit N leading account name parts - - This command lists account names - all of them by default. or just -the ones which have been used in transactions, or declared with -'account' directives, or used but not declared, or declared but not -used, or just the first account name matched by a pattern. - - You can add query arguments to select a subset of transactions or -accounts. - - 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 shows valid account directives which could be -pasted into a journal file. This is useful together with '--undeclared' -when updating your account declarations to satisfy 'hledger check -accounts'. - - The '--find' flag can be used to look up a single account name, in -the same way that the 'aregister' command does. It returns the -alphanumerically-first matched account name, or if none can be found, it -fails with a non-zero exit code. - - Examples: - -$ hledger accounts -assets:bank:checking -assets:bank:saving -assets:cash -expenses:food -expenses:supplies -income:gifts -income:salary -liabilities:debts - -$ hledger accounts --undeclared --directives >> $LEDGER_FILE -$ hledger check accounts - - -File: hledger.info, Node: codes, Next: commodities, Prev: accounts, Up: Basic report commands - -27.2 codes -========== - -List the codes seen in transactions, in the order parsed. - -Flags: -no command-specific flags - - This command prints the value of each transaction's code field, in -the order transactions were parsed. The transaction code is an optional -value written in parentheses between the date and description, often -used to store a cheque number, order number or similar. - - Transactions aren't required to have a code, and missing or empty -codes will not be shown by default. With the '-E'/'--empty' flag, they -will be printed as blank lines. - - You can add a query to select a subset of transactions. - - Examples: - -2022/1/1 (123) Supermarket - Food $5.00 - Checking - -2022/1/2 (124) Post Office - Postage $8.32 - Checking - -2022/1/3 Supermarket - Food $11.23 - Checking - -2022/1/4 (126) Post Office - Postage $3.21 - Checking - -$ hledger codes -123 -124 -126 - -$ hledger codes -E -123 -124 - -126 - - -File: hledger.info, Node: commodities, Next: descriptions, Prev: codes, Up: Basic report commands - -27.3 commodities -================ - -List the commodity symbols used or declared in the journal. - -Flags: - --used list commodities used - --declared list commodities declared - --undeclared list commodities used but not declared - --unused list commodities declared but not used - - This command lists commodity symbols/names - all of them by default, -or just the ones which have been used in transactions or 'P' directives, -or declared with 'commodity' directives, or used but not declared, or -declared but not used. - - You can add cur: query arguments to further limit the commodities. - - -File: hledger.info, Node: descriptions, Next: files, Prev: commodities, Up: Basic report commands - -27.4 descriptions -================= - -List the unique descriptions used in transactions. - -Flags: -no command-specific flags - - This command lists the unique descriptions that appear in -transactions, in alphabetic order. You can add a query to select a -subset of transactions. - - Example: - -$ hledger descriptions -Store Name -Gas Station | Petrol -Person A - - -File: hledger.info, Node: files, Next: notes, Prev: descriptions, Up: Basic report commands - -27.5 files -========== - -List all files included in the journal. With a REGEX argument, only -file names matching the regular expression (case sensitive) are shown. - -Flags: -no command-specific flags - - -File: hledger.info, Node: notes, Next: payees, Prev: files, Up: Basic report commands - -27.6 notes -========== - -List the unique notes that appear in transactions. - -Flags: -no command-specific flags - - This command lists the unique notes that appear in transactions, in -alphabetic order. You can add a query to select a subset of -transactions. The note is the part of the transaction description after -a | character (or if there is no |, the whole description). - - Example: - -$ hledger notes -Petrol -Snacks - - -File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: Basic report commands - -27.7 payees -=========== - -List the payee/payer names used or declared in the journal. - -Flags: - --used list payees used - --declared list payees declared - --undeclared list payees used but not declared - --unused list payees declared but not used - - This command lists unique payee/payer names - all of them by default, -or just the ones which have been used in transaction descriptions, or -declared with 'payee' directives, or used but not declared, or declared -but not used. - - The payee/payer name 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 or -payees. - - Example: - -$ hledger payees -Store Name -Gas Station -Person A - - -File: hledger.info, Node: prices, Next: stats, Prev: payees, Up: Basic report commands - -27.8 prices -=========== - -Print the market prices declared with P directives. With --infer-market-prices, also show any additional prices inferred from -costs. With -show-reverse, also show additional prices inferred by -reversing known prices. - -Flags: - --show-reverse also show the prices inferred by reversing known - prices - - Price amounts are always displayed with their full precision, except -for reverse prices which are limited to 8 decimal digits. - - Prices can be filtered by a date:, cur: or amt: query. - - Generally if you run this command with -infer-market-prices --show-reverse, it will show the same prices used internally to calculate -value reports. But if in doubt, you can inspect those directly by -running the value report with -debug=2. - - -File: hledger.info, Node: stats, Next: tags, Prev: prices, Up: Basic report commands - -27.9 stats -========== - -Show journal and performance statistics. - -Flags: - -v --verbose show more detailed output - -o --output-file=FILE write output to FILE. - - The stats command shows summary information for the whole journal, or -a matched part of it. With a reporting interval, it shows a report for -each report period. - - The default output is fairly impersonal, though it reveals the main -file name. With '-v/--verbose', more details are shown, like file -paths, included files, and commodity names. - - It also shows some run time statistics: - - * elapsed time - * throughput: the number of transactions processed per second - * live: the peak memory in use by the program to do its work - * alloc: the peak memory allocation from the OS as seen by GHC. - Measuring this externally, eg with GNU time, is more accurate; - usually that will be a larger number; sometimes (with swapping?) - smaller. - - The 'stats' command's run time is similar to that of a balance -report. - - Example: - -$ hledger stats -f examples/1ktxns-1kaccts.journal -Main file : .../1ktxns-1kaccts.journal -Included files : 0 -Txns span : 2000-01-01 to 2002-09-27 (1000 days) -Last txn : 2002-09-26 (7827 days ago) -Txns : 1000 (1.0 per day) -Txns last 30 days : 0 (0.0 per day) -Txns last 7 days : 0 (0.0 per day) -Payees/descriptions : 1000 -Accounts : 1000 (depth 10) -Commodities : 26 -Market prices : 1000 -Runtime stats : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc - - This command supports the -o/-output-file option (but not --O/-output-format). - - -File: hledger.info, Node: tags, Prev: stats, Up: Basic report commands - -27.10 tags -========== - -List the tag names used or declared in the journal, or their values. - -Flags: - --used list tags used - --declared list tags declared - --undeclared list tags used but not declared - --unused list tags declared but not used - --values list tag values instead of tag names - --parsed show them in the order they were parsed (mostly), - including duplicates - - This command lists tag names - all of them by default, or just the -ones which have been used on transactions/postings/accounts, or declared -with 'tag' directives, or used but not declared, or declared but not -used. - - You can add one TAGREGEX argument, to show only tags whose name is -matched by this case-insensitive, infix-matching regular expression. - - After that, you can add query arguments to filter the transactions, -postings, or accounts providing tags. - - With '--values', 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.) - - Remember that accounts also acquire tags from their parents; postings -also acquire tags from their account and transaction; and transactions -also acquire tags from their postings. - - -File: hledger.info, Node: Standard report commands, Next: Advanced report commands, Prev: Basic report commands, Up: Top - -28 Standard report commands -*************************** - -* Menu: - -* print:: -* aregister:: -* register:: -* balancesheet:: -* balancesheetequity:: -* cashflow:: -* incomestatement:: - - -File: hledger.info, Node: print, Next: aregister, Up: Standard report commands - -28.1 print -========== - -Show full journal entries, representing transactions. - -Flags: - -x --explicit show all amounts explicitly - --invert display all amounts with reversed sign - --location add tags showing file paths and line numbers - -m --match=DESC fuzzy search for one recent transaction with - description closest to DESC - --new show only newer-dated transactions added in each - file since last run - --round=TYPE how much rounding or padding should be done when - displaying amounts ? - none - show original decimal digits, - as in journal (default) - soft - just add or remove decimal zeros - to match precision - hard - round posting amounts to precision - (can unbalance transactions) - all - also round cost amounts to precision - (can unbalance transactions) - --base-url=URLPREFIX in html output, generate links to hledger-web, - with this prefix. (Usually the base url shown by - hledger-web; can also be relative.) - -O --output-format=FMT select the output format. Supported formats: - txt, beancount, csv, tsv, html, fods, json, sql. - -o --output-file=FILE write output to FILE. A file extension matching - one of the above formats selects that format. - - The print command displays full journal entries (transactions) from -the journal file, sorted by date (or with '--date2', by secondary date). - - Directives and inter-transaction comments are not shown, currently. -This means the print command is somewhat lossy, and if you are using it -to reformat/regenerate your journal you should take care to also copy -over the directives and inter-transaction comments. - - Eg: - -$ hledger print -f examples/sample.journal date:200806 -2008/06/01 gift - assets:bank:checking $1 - income:gifts $-1 - -2008/06/02 save - assets:bank:saving $1 - assets:bank:checking $-1 - -2008/06/03 * eat & shop - expenses:food $1 - expenses:supplies $1 - assets:cash $-2 - -* Menu: - -* print explicitness:: -* print amount style:: -* print parseability:: -* print other features:: -* print output format:: - - -File: hledger.info, Node: print explicitness, Next: print amount style, Up: print - -28.1.1 print explicitness -------------------------- - -Normally, whether posting amounts are implicit or explicit is preserved. -For example, when an amount is omitted in the journal, it will not -appear in the output. Similarly, if a conversion cost is implied but -not written, it will not appear in the output. - - You can use the '-x'/'--explicit' flag to force explicit display of -all amounts and costs. This can be useful for troubleshooting or for -making your journal more readable and robust against data entry errors. -'-x' is also implied by using any of '-B','-V','-X','--value'. - - The '-x'/'--explicit' flag will cause any postings with a -multi-commodity amount (which can arise when a multi-commodity -transaction has an implicit amount) to be split into multiple -single-commodity postings, keeping the output parseable. - - -File: hledger.info, Node: print amount style, Next: print parseability, Prev: print explicitness, Up: print - -28.1.2 print amount style -------------------------- - -Amounts are shown right-aligned within each transaction (but not aligned -across all transactions; you can do that with ledger-mode in Emacs). - - Amounts will be (mostly) normalised to their commodity display style: -their symbol placement, decimal mark, and digit group marks will be made -consistent. By default, decimal digits are shown as they are written in -the journal. - - With the '--round' (_Added in 1.32_) option, 'print' will try -increasingly hard to display decimal digits according to the commodity -display styles: - - * '--round=none' show amounts with original precisions (default) - * '--round=soft' add/remove decimal zeros in amounts (except costs) - * '--round=hard' round amounts (except costs), possibly hiding - significant digits - * '--round=all' round all amounts and costs - - 'soft' is good for non-lossy cleanup, formatting amounts more -consistently where it's safe to do so. - - 'hard' and 'all' can cause 'print' to show invalid unbalanced journal -entries; they may be useful eg for stronger cleanup, with manual fixups -when needed. - - -File: hledger.info, Node: print parseability, Next: print other features, Prev: print amount style, Up: print - -28.1.3 print parseability -------------------------- - -print's output is usually a valid hledger journal, and you can process -it again with a second hledger command. This can be useful for certain -kinds of search (though the same can be achieved with 'expr:' queries -now): - -# Show running total of food expenses paid from cash. -# -f- reads from stdin. -I/--ignore-assertions is sometimes needed. -$ hledger print assets:cash | hledger -f- -I reg expenses:food - - There are some situations where print's output can become -unparseable: - - * Value reporting affects posting amounts but not balance assertion - or balance assignment amounts, potentially causing those to fail. - * Auto postings can generate postings with too many missing amounts. - * Account aliases can generate bad account names. - - -File: hledger.info, Node: print other features, Next: print output format, Prev: print parseability, Up: print - -28.1.4 print, other features ----------------------------- - -With '-B'/'--cost', amounts with costs are shown converted to cost. - - With '--invert', posting amounts are shown with their sign flipped. -It could be useful if you have accidentally recorded some transactions -with the wrong signs. - - With '--new', print shows only transactions it has not seen on a -previous run. This uses the same deduplication system as the 'import' -command. (See import's docs for details.) - - With '-m DESC'/'--match=DESC', print shows one recent transaction -whose description is most similar to DESC. DESC should contain at least -two characters. If there is no similar-enough match, no transaction -will be shown and the program exit code will be non-zero. - - With '--location', print adds the source file and line number to -every transaction, as a tag. - - -File: hledger.info, Node: print output format, Prev: print other features, Up: print - -28.1.5 print output format --------------------------- - -This command also supports the output destination and output format -options The output formats supported are 'txt', 'beancount' (_Added in -1.32_), 'csv', 'tsv' (_Added in 1.32_), 'json' and 'sql'. - - The 'beancount' format tries to produce Beancount-compatible output, -as follows: - - * Transaction and postings with unmarked status are converted to - cleared ('*') status. - * Transactions' payee and note are backslash-escaped and - double-quote-escaped and wrapped in double quotes. - * Transaction tags are copied to Beancount #tag format. - * Commodity symbols are converted to upper case, and a small number - of currency symbols like '$' are converted to the corresponding - currency names. - * Account name parts are capitalised and unsupported characters are - replaced with '-'. If an account name part does not begin with a - letter, or if the first part is not Assets, Liabilities, Equity, - Income, or Expenses, an error is raised. (Use '--alias' options to - bring your accounts into compliance.) - * An 'open' directive is generated for each account used, on the - earliest transaction date. - - Some limitations: - - * Balance assertions are removed. - * Balance assignments become missing amounts. - * Virtual and balanced virtual postings become regular postings. - * Directives are not converted. - - Here's an example of print's CSV output: - -$ hledger print -Ocsv -"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" -"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","","" -"1","2008/01/01","","","","income","","income:salary","-1","$","1","","","" -"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","","" -"2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","","" -"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","","" -"3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","","" -"4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","","" -"4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","","" -"4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","","" -"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" -"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" - - * There is one CSV record per posting, with the parent transaction's - fields repeated. - * The "txnidx" (transaction index) field shows which postings belong - to the same transaction. (This number might change if transactions - are reordered within the file, files are parsed/included in a - different order, etc.) - * The amount is separated into "commodity" (the symbol) and "amount" - (numeric quantity) fields. - * The numeric amount is repeated in either the "credit" or "debit" - column, for convenience. (Those names are not accurate in the - accounting sense; it just puts negative amounts under credit and - zero or greater amounts under debit.) - - -File: hledger.info, Node: aregister, Next: register, Prev: print, Up: Standard report commands - -28.2 aregister -============== - -(areg) - - Show the transactions and running balances in one account, with each -transaction on one line. - -Flags: - --txn-dates filter strictly by transaction date, not posting - date. Warning: this can show a wrong running - balance. - --no-elide don't show only 2 commodities per amount - --cumulative accumulation mode: show running total from report - start date - -H --historical accumulation mode: show historical running - total/balance (includes postings before report - start date) (default) - --invert display all amounts with reversed sign - --heading=YN show heading row above table: yes (default) or no - -w --width=N set output width (default: terminal width). -wN,M - sets description width as well. - --align-all guarantee alignment across all lines (slower) - -O --output-format=FMT select the output format. Supported formats: - txt, html, csv, tsv, json. - -o --output-file=FILE write output to FILE. A file extension matching - one of the above formats selects that format. - - 'aregister' shows the overall transactions affecting a particular -account (and any subaccounts). Each report line represents one -transaction in this account. Transactions before the report start date -are included in the running balance ('--historical' mode is the -default). You can suppress this behaviour using the '--cumulative' -option. - - This is a more "real world", bank-like view than the 'register' -command (which shows individual postings, possibly from multiple -accounts, not necessarily in historical mode). As a quick rule of -thumb: - use 'aregister' for reviewing and reconciling real-world -asset/liability accounts - use 'register' for reviewing detailed -revenues/expenses. - - 'aregister' requires one argument: the account to report on. You can -write either the full account name, or a case-insensitive regular -expression which will select the alphabetically first matched account. - - When there are multiple matches, the alphabetically-first choice can -be surprising; eg if you have 'assets:per:checking 1' and -'assets:biz:checking 2' accounts, 'hledger areg checking' would select -'assets:biz:checking 2'. It's just a convenience to save typing, so if -in doubt, write the full account name, or a distinctive substring that -matches uniquely. - - Transactions involving subaccounts of this account will also be -shown. 'aregister' ignores depth limits, so its final total will always -match a historical balance report with similar arguments. - - Any additional arguments form a query which will filter the -transactions shown. Note some queries will disturb the running balance, -causing it to be different from the account's real-world running -balance. - - An example: this shows the transactions and historical running -balance during july, in the first account whose name contains -"checking": - -$ hledger areg checking date:jul - - Each 'aregister' line item shows: - - * the transaction's date (or the relevant posting's date if - different, see below) - * the names of all the other account(s) involved in this transaction - (probably abbreviated) - * the total change to this account's balance from this transaction - * the account's historical running balance after this transaction. - - Transactions making a net change of zero are not shown by default; -add the '-E/--empty' flag to show them. - - For performance reasons, column widths are chosen based on the first -1000 lines; this means unusually wide values in later lines can cause -visual discontinuities as column widths are adjusted. If you want to -ensure perfect alignment, at the cost of more time and memory, use the -'--align-all' flag. - - By default, 'aregister' shows a heading above the data. However, -when reporting in a language different from English, it is easier to -omit this heading and prepend your own one. For this purpose, use the -'--heading=no' option. - - This command also supports the output destination and output format -options. The output formats supported are 'txt', 'csv', 'tsv' (_Added -in 1.32_), 'html', 'fods' (_Added in 1.41_) and 'json'. - -* Menu: - -* aregister and posting dates:: - - -File: hledger.info, Node: aregister and posting dates, Up: aregister - -28.2.1 aregister and posting dates ----------------------------------- - -aregister always shows one line (and date and amount) per transaction. -But sometimes transactions have postings with different dates. Also, -not all of a transaction's postings may be within the report period. To -resolve this, aregister shows the earliest of the transaction's date and -posting dates that is in-period, and the sum of the in-period postings. -In other words it will show a combined line item with just the earliest -date, and the running balance will (temporarily, until the transaction's -last posting) be inaccurate. Use 'register -H' if you need to see the -individual postings. - - There is also a '--txn-dates' flag, which filters strictly by -transaction date, ignoring posting dates. This too can cause an -inaccurate running balance. - - -File: hledger.info, Node: register, Next: balancesheet, Prev: aregister, Up: Standard report commands - -28.3 register -============= - -(reg) - - Show postings and their running total. - -Flags: - --cumulative accumulation mode: show running total from report - start date (default) - -H --historical accumulation mode: show historical running - total/balance (includes postings before report - start date) - -A --average show running average of posting amounts instead - of total (implies --empty) - -m --match=DESC fuzzy search for one recent posting with - description closest to DESC - -r --related show postings' siblings instead - --invert display all amounts with reversed sign - --sort=FIELDS sort by: date, desc, account, amount, absamount, - or a comma-separated combination of these. For a - descending sort, prefix with -. (Default: date) - -w --width=N set output width (default: terminal width). -wN,M - sets description width as well. - --align-all guarantee alignment across all lines (slower) - --base-url=URLPREFIX in html output, generate links to hledger-web, - with this prefix. (Usually the base url shown by - hledger-web; can also be relative.) - -O --output-format=FMT select the output format. Supported formats: - txt, csv, tsv, html, fods, json. - -o --output-file=FILE write output to FILE. A file extension matching - one of the above formats selects that format. - - The register command displays matched postings, across all accounts, -in date order, with their running total or running historical balance. -(See also the 'aregister' command, which shows matched transactions in a -specific account.) - - register normally shows line per posting, but note that -multi-commodity amounts will occupy multiple lines (one line per -commodity). - - It is typically used with a query selecting a particular account, to -see that account's activity: - -$ hledger register checking -2008/01/01 income assets:bank:checking $1 $1 -2008/06/01 gift assets:bank:checking $1 $2 -2008/06/02 save assets:bank:checking $-1 $1 -2008/12/31 pay off assets:bank:checking $-1 0 - - With '--date2', it shows and sorts by secondary date instead. - - For performance reasons, column widths are chosen based on the first -1000 lines; this means unusually wide values in later lines can cause -visual discontinuities as column widths are adjusted. If you want to -ensure perfect alignment, at the cost of more time and memory, use the -'--align-all' flag. - - The '--historical'/'-H' flag adds the balance from any undisplayed -prior postings to the running total. This is useful when you want to -see only recent activity, with a historically accurate running balance: - -$ hledger register checking -b 2008/6 --historical -2008/06/01 gift assets:bank:checking $1 $2 -2008/06/02 save assets:bank:checking $-1 $1 -2008/12/31 pay off assets:bank:checking $-1 0 - - The '--depth' option limits the amount of sub-account detail -displayed. - - The '--average'/'-A' flag shows the running average posting amount -instead of the running total (so, the final number displayed is the -average for the whole report period). This flag implies '--empty' (see -below). It is affected by '--historical'. It works best when showing -just one account and one commodity. - - The '--related'/'-r' flag shows the _other_ postings in the -transactions of the postings which would normally be shown. - - The '--invert' flag negates all amounts. For example, it can be used -on an income account where amounts are normally displayed as negative -numbers. It's also useful to show postings on the checking account -together with the related account: - - The '--sort=FIELDS' flag sorts by the fields given, which can be any -of 'account', 'amount', 'absamount', 'date', or 'desc'/'description', -optionally separated by commas. For example, '--sort account,amount' -will group all transactions in each account, sorted by transaction -amount. Each field can be negated by a preceding '-', so '--sort --amount' will show transactions ordered from smallest amount to largest -amount. - -$ hledger register --related --invert assets:checking - - With a reporting interval, register shows summary postings, one per -interval, aggregating the postings to each account: - -$ hledger register --monthly income -2008/01 income:salary $-1 $-1 -2008/06 income:gifts $-1 $-2 - - Periods with no activity, and summary postings with a zero amount, -are not shown by default; use the '--empty'/'-E' flag to see them: - -$ hledger register --monthly income -E -2008/01 income:salary $-1 $-1 -2008/02 0 $-1 -2008/03 0 $-1 -2008/04 0 $-1 -2008/05 0 $-1 -2008/06 income:gifts $-1 $-2 -2008/07 0 $-2 -2008/08 0 $-2 -2008/09 0 $-2 -2008/10 0 $-2 -2008/11 0 $-2 -2008/12 0 $-2 - - Often, you'll want to see just one line per interval. The '--depth' -option helps with this, causing subaccounts to be aggregated: - -$ hledger register --monthly assets --depth 1 -2008/01 assets $1 $1 -2008/06 assets $-1 0 -2008/12 assets $-1 $-1 - - Note when using report intervals, if you specify start/end dates -these will be adjusted outward if necessary to contain a whole number of -intervals. This ensures that the first and last intervals are full -length and comparable to the others in the report. - - With '-m DESC'/'--match=DESC', register does a fuzzy search for one -recent posting whose description is most similar to DESC. DESC should -contain at least two characters. If there is no similar-enough match, -no posting will be shown and the program exit code will be non-zero. - -* Menu: - -* Custom register output:: - - -File: hledger.info, Node: Custom register output, Up: register - -28.3.1 Custom register output ------------------------------ - -register normally uses the full terminal width (or 80 columns if it -can't detect that). You can override this with the '--width'/'-w' -option. - - The description and account columns normally share the space equally -(about half of (width - 40) each). You can adjust this by adding a -description width as part of -width's argument, comma-separated: -'--width W,D' . Here's a diagram (won't display correctly in -help): - -<--------------------------------- width (W) ----------------------------------> -date (10) description (D) account (W-41-D) amount (12) balance (12) -DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA - - and some examples: - -$ hledger reg # use terminal width (or 80 on windows) -$ hledger reg -w 100 # use width 100 -$ hledger reg -w 100,40 # set overall width 100, description width 40 - - This command also supports the output destination and output format -options The output formats supported are 'txt', 'csv', 'tsv' (_Added in -1.32_), and 'json'. - - -File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: register, Up: Standard report commands - -28.4 balancesheet -================= - -(bs) - - Show the end balances in asset and liability accounts. Amounts are -shown with normal positive sign, as in conventional financial -statements. - -Flags: - --sum calculation mode: show sum of posting amounts - (default) - --valuechange calculation mode: show total change of value of - period-end historical balances (caused by deposits, - withdrawals, market price fluctuations) - --gain calculation mode: show unrealised capital - gain/loss (historical balance value minus cost - basis) - --count calculation mode: show the count of postings - --change accumulation mode: accumulate amounts from column - start to column end (in multicolumn reports) - --cumulative accumulation mode: accumulate amounts from report - start (specified by e.g. -b/--begin) to column end - -H --historical accumulation mode: accumulate amounts from - journal start to column end (includes postings - before report start date) (default) - -l --flat list/tree mode: show accounts as a flat list - (default). Amounts exclude subaccount amounts, - except where the account is depth-clipped. - -t --tree list/tree mode: show accounts as a tree. Amounts - include subaccount amounts. - --drop=N in list mode, omit N leading account name parts - --declared include non-parent declared accounts (best used - with -E) - -A --average show a row average column (in multicolumn - reports) - -T --row-total show a row total column (in multicolumn reports) - --summary-only display only row summaries (e.g. row total, - average) (in multicolumn reports) - -N --no-total omit the final total row - --no-elide in tree mode, don't squash boring parent accounts - --format=FORMATSTR use this custom line format (in simple reports) - -S --sort-amount sort by amount instead of account code/name - -% --percent express values in percentage of each column's - total - --layout=ARG how to show multi-commodity amounts: - 'wide[,WIDTH]': all commodities on one line - 'tall' : each commodity on a new line - 'bare' : bare numbers, symbols in a column - --base-url=URLPREFIX in html output, generate hyperlinks to - hledger-web, with this prefix. (Usually the base - url shown by hledger-web; can also be relative.) - -O --output-format=FMT select the output format. Supported formats: - txt, html, csv, tsv, json. - -o --output-file=FILE write output to FILE. A file extension matching - one of the above formats selects that format. - - This command displays a balance sheet, showing historical ending -balances of asset and liability accounts. (To see equity as well, use -the balancesheetequity command.) - - Accounts declared with the 'Asset', 'Cash' or 'Liability' type are -shown (see account types). Or if no such accounts are declared, it -shows top-level accounts named 'asset' or 'liability' (case insensitive, -plurals allowed) and their subaccounts. - - Example: - -$ hledger balancesheet -Balance Sheet 2008-12-31 - - || 2008-12-31 -====================++============ - Assets || ---------------------++------------ - assets:bank:saving || $1 - assets:cash || $-2 ---------------------++------------ - || $-1 -====================++============ - Liabilities || ---------------------++------------ - liabilities:debts || $-1 ---------------------++------------ - || $-1 -====================++============ - Net: || 0 - - This command is a higher-level variant of the 'balance' command, and -supports many of that command's features, such as multi-period reports. -It is similar to 'hledger balance -H assets liabilities', but with -smarter account detection, and liabilities displayed with their sign -flipped. - - This command also supports the output destination and output format -options The output formats supported are 'txt', 'csv', 'tsv' (_Added in -1.32_), 'html', and 'json'. - - -File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: Standard report commands - -28.5 balancesheetequity -======================= - -(bse) - - This command displays a balance sheet, showing historical ending -balances of asset, liability and equity accounts. Amounts are shown -with normal positive sign, as in conventional financial statements. - -Flags: - --sum calculation mode: show sum of posting amounts - (default) - --valuechange calculation mode: show total change of value of - period-end historical balances (caused by deposits, - withdrawals, market price fluctuations) - --gain calculation mode: show unrealised capital - gain/loss (historical balance value minus cost - basis) - --count calculation mode: show the count of postings - --change accumulation mode: accumulate amounts from column - start to column end (in multicolumn reports) - --cumulative accumulation mode: accumulate amounts from report - start (specified by e.g. -b/--begin) to column end - -H --historical accumulation mode: accumulate amounts from - journal start to column end (includes postings - before report start date) (default) - -l --flat list/tree mode: show accounts as a flat list - (default). Amounts exclude subaccount amounts, - except where the account is depth-clipped. - -t --tree list/tree mode: show accounts as a tree. Amounts - include subaccount amounts. - --drop=N in list mode, omit N leading account name parts - --declared include non-parent declared accounts (best used - with -E) - -A --average show a row average column (in multicolumn - reports) - -T --row-total show a row total column (in multicolumn reports) - --summary-only display only row summaries (e.g. row total, - average) (in multicolumn reports) - -N --no-total omit the final total row - --no-elide in tree mode, don't squash boring parent accounts - --format=FORMATSTR use this custom line format (in simple reports) - -S --sort-amount sort by amount instead of account code/name - -% --percent express values in percentage of each column's - total - --layout=ARG how to show multi-commodity amounts: - 'wide[,WIDTH]': all commodities on one line - 'tall' : each commodity on a new line - 'bare' : bare numbers, symbols in a column - --base-url=URLPREFIX in html output, generate hyperlinks to - hledger-web, with this prefix. (Usually the base - url shown by hledger-web; can also be relative.) - -O --output-format=FMT select the output format. Supported formats: - txt, html, csv, tsv, json. - -o --output-file=FILE write output to FILE. A file extension matching - one of the above formats selects that format. - - This report shows accounts declared with the 'Asset', 'Cash', -'Liability' or 'Equity' type (see account types). Or if no such -accounts are declared, it shows top-level accounts named 'asset', -'liability' or 'equity' (case insensitive, plurals allowed) and their -subaccounts. - - Example: - -$ hledger balancesheetequity -Balance Sheet With Equity 2008-12-31 - - || 2008-12-31 -====================++============ - Assets || ---------------------++------------ - assets:bank:saving || $1 - assets:cash || $-2 ---------------------++------------ - || $-1 -====================++============ - Liabilities || ---------------------++------------ - liabilities:debts || $-1 ---------------------++------------ - || $-1 -====================++============ - Equity || ---------------------++------------ ---------------------++------------ - || 0 -====================++============ - Net: || 0 - - This command is a higher-level variant of the 'balance' command, and -supports many of that command's features, such as multi-period reports. -It is similar to 'hledger balance -H assets liabilities equity', but -with smarter account detection, and liabilities/equity displayed with -their sign flipped. - - This report is the easiest way to see if the accounting equation -(A+L+E = 0) is satisfied (after you have done a 'close --retain' to -merge revenues and expenses with equity, and perhaps added -'--infer-equity' to balance your commodity conversions). - - This command also supports the output destination and output format -options The output formats supported are 'txt', 'csv', 'tsv', 'html', -and 'json'. - - -File: hledger.info, Node: cashflow, Next: incomestatement, Prev: balancesheetequity, Up: Standard report commands - -28.6 cashflow -============= - -(cf) - - This command displays a (simple) cashflow statement, showing the -inflows and outflows affecting "cash" (ie, liquid, easily convertible) -assets. Amounts are shown with normal positive sign, as in conventional -financial statements. - -Flags: - --sum calculation mode: show sum of posting amounts - (default) - --valuechange calculation mode: show total change of value of - period-end historical balances (caused by deposits, - withdrawals, market price fluctuations) - --gain calculation mode: show unrealised capital - gain/loss (historical balance value minus cost - basis) - --count calculation mode: show the count of postings - --change accumulation mode: accumulate amounts from column - start to column end (in multicolumn reports) - (default) - --cumulative accumulation mode: accumulate amounts from report - start (specified by e.g. -b/--begin) to column end - -H --historical accumulation mode: accumulate amounts from - journal start to column end (includes postings - before report start date) - -l --flat list/tree mode: show accounts as a flat list - (default). Amounts exclude subaccount amounts, - except where the account is depth-clipped. - -t --tree list/tree mode: show accounts as a tree. Amounts - include subaccount amounts. - --drop=N in list mode, omit N leading account name parts - --declared include non-parent declared accounts (best used - with -E) - -A --average show a row average column (in multicolumn - reports) - -T --row-total show a row total column (in multicolumn reports) - --summary-only display only row summaries (e.g. row total, - average) (in multicolumn reports) - -N --no-total omit the final total row - --no-elide in tree mode, don't squash boring parent accounts - --format=FORMATSTR use this custom line format (in simple reports) - -S --sort-amount sort by amount instead of account code/name - -% --percent express values in percentage of each column's - total - --layout=ARG how to show multi-commodity amounts: - 'wide[,WIDTH]': all commodities on one line - 'tall' : each commodity on a new line - 'bare' : bare numbers, symbols in a column - --base-url=URLPREFIX in html output, generate hyperlinks to - hledger-web, with this prefix. (Usually the base - url shown by hledger-web; can also be relative.) - -O --output-format=FMT select the output format. Supported formats: - txt, html, csv, tsv, json. - -o --output-file=FILE write output to FILE. A file extension matching - one of the above formats selects that format. - - This report shows accounts declared with the 'Cash' type (see account -types). Or if no such accounts are declared, it shows accounts - - * under a top-level account named 'asset' (case insensitive, plural - allowed) - * whose name contains some variation of 'cash', 'bank', 'checking' or - 'saving'. - - More precisely: all accounts matching this case insensitive regular -expression: - - '^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$)' - - and their subaccounts. - - An example cashflow report: - -$ hledger cashflow -Cashflow Statement 2008 - - || 2008 -====================++====== - Cash flows || ---------------------++------ - assets:bank:saving || $1 - assets:cash || $-2 ---------------------++------ - || $-1 - - This command is a higher-level variant of the 'balance' command, and -supports many of that command's features, such as multi-period reports. -It is similar to 'hledger balance assets not:fixed not:investment -not:receivable', but with smarter account detection. - - This command also supports the output destination and output format -options The output formats supported are 'txt', 'csv', 'tsv' (_Added in -1.32_), 'html', and 'json'. - - -File: hledger.info, Node: incomestatement, Prev: cashflow, Up: Standard report commands - -28.7 incomestatement -==================== - -(is) - - Show revenue inflows and expense outflows during the report period. -Amounts are shown with normal positive sign, as in conventional -financial statements. - -Flags: - --sum calculation mode: show sum of posting amounts - (default) - --valuechange calculation mode: show total change of value of - period-end historical balances (caused by deposits, - withdrawals, market price fluctuations) - --gain calculation mode: show unrealised capital - gain/loss (historical balance value minus cost - basis) - --count calculation mode: show the count of postings - --change accumulation mode: accumulate amounts from column - start to column end (in multicolumn reports) - (default) - --cumulative accumulation mode: accumulate amounts from report - start (specified by e.g. -b/--begin) to column end - -H --historical accumulation mode: accumulate amounts from - journal start to column end (includes postings - before report start date) - -l --flat list/tree mode: show accounts as a flat list - (default). Amounts exclude subaccount amounts, - except where the account is depth-clipped. - -t --tree list/tree mode: show accounts as a tree. Amounts - include subaccount amounts. - --drop=N in list mode, omit N leading account name parts - --declared include non-parent declared accounts (best used - with -E) - -A --average show a row average column (in multicolumn - reports) - -T --row-total show a row total column (in multicolumn reports) - --summary-only display only row summaries (e.g. row total, - average) (in multicolumn reports) - -N --no-total omit the final total row - --no-elide in tree mode, don't squash boring parent accounts - --format=FORMATSTR use this custom line format (in simple reports) - -S --sort-amount sort by amount instead of account code/name - -% --percent express values in percentage of each column's - total - --layout=ARG how to show multi-commodity amounts: - 'wide[,WIDTH]': all commodities on one line - 'tall' : each commodity on a new line - 'bare' : bare numbers, symbols in a column - --base-url=URLPREFIX in html output, generate hyperlinks to - hledger-web, with this prefix. (Usually the base - url shown by hledger-web; can also be relative.) - -O --output-format=FMT select the output format. Supported formats: - txt, html, csv, tsv, json. - -o --output-file=FILE write output to FILE. A file extension matching - one of the above formats selects that format. - - This command displays an income statement, showing revenues and -expenses during one or more periods. - - It shows accounts declared with the 'Revenue' or 'Expense' type (see -account types). Or if no such accounts are declared, it shows top-level -accounts named 'revenue' or 'income' or 'expense' (case insensitive, -plurals allowed) and their subaccounts. - - Example: - -$ hledger incomestatement -Income Statement 2008 - - || 2008 -===================++====== - Revenues || --------------------++------ - income:gifts || $1 - income:salary || $1 --------------------++------ - || $2 -===================++====== - Expenses || --------------------++------ - expenses:food || $1 - expenses:supplies || $1 --------------------++------ - || $2 -===================++====== - Net: || 0 - - This command is a higher-level variant of the 'balance' command, and -supports many of that command's features, such as multi-period reports. -It is similar to 'hledger balance '(revenues|income)' expenses', but -with smarter account detection, and revenues/income displayed with their -sign flipped. - - This command also supports the output destination and output format -options The output formats supported are 'txt', 'csv', 'tsv' (_Added in -1.32_), 'html', and 'json'. - - -File: hledger.info, Node: Advanced report commands, Next: Chart commands, Prev: Standard report commands, Up: Top - -29 Advanced report commands -*************************** - -* Menu: - -* balance:: -* roi:: - - -File: hledger.info, Node: balance, Next: roi, Up: Advanced report commands - -29.1 balance -============ - -(bal) - - A flexible, general purpose "summing" report that shows accounts with -some kind of numeric data. This can be balance changes per period, end -balances, budget performance, unrealised capital gains, etc. - -Flags: - --sum calculation mode: show sum of posting amounts - (default) - --valuechange calculation mode: show total change of value of - period-end historical balances (caused by deposits, - withdrawals, market price fluctuations) - --gain calculation mode: show unrealised capital - gain/loss (historical balance value minus cost - basis) - --budget[=DESCPAT] calculation mode: show sum of posting amounts - together with budget goals defined by periodic - transactions. With a DESCPAT argument (must be - separated by = not space), - use only periodic transactions with matching - description - (case insensitive substring match). - --count calculation mode: show the count of postings - --change accumulation mode: accumulate amounts from column - start to column end (in multicolumn reports, - default) - --cumulative accumulation mode: accumulate amounts from report - start (specified by e.g. -b/--begin) to column end - -H --historical accumulation mode: accumulate amounts from - journal start to column end (includes postings - before report start date) - -l --flat list/tree mode: show accounts as a flat list - (default). Amounts exclude subaccount amounts, - except where the account is depth-clipped. - -t --tree list/tree mode: show accounts as a tree. Amounts - include subaccount amounts. - --drop=N in list mode, omit N leading account name parts - --declared include non-parent declared accounts (best used - with -E) - -A --average show a row average column (in multicolumn - reports) - -T --row-total show a row total column (in multicolumn reports) - --summary-only display only row summaries (e.g. row total, - average) (in multicolumn reports) - -N --no-total omit the final total row - --no-elide in tree mode, don't squash boring parent accounts - --format=FORMATSTR use this custom line format (in simple reports) - -S --sort-amount sort by amount instead of account code/name (in - flat mode). With multiple columns, sorts by the row - total, or by row average if that is displayed. - -% --percent express values in percentage of each column's - total - -r --related show the other accounts transacted with, instead - --invert display all amounts with reversed sign - --transpose switch rows and columns (use vertical time axis) - --layout=ARG how to lay out multi-commodity amounts and the - overall table: - 'wide[,W]': commodities on same line, up to W wide - 'tall' : commodities on separate lines - 'bare' : commodity symbols in a separate column - 'tidy' : each data field in its own column - --base-url=URLPREFIX in html output, generate links to hledger-web, - with this prefix. (Usually the base url shown by - hledger-web; can also be relative.) - -O --output-format=FMT select the output format. Supported formats: - txt, html, csv, tsv, json, fods. - -o --output-file=FILE write output to FILE. A file extension matching - one of the above formats selects that format. - - 'balance' is one of hledger's oldest and most versatile commands, for -listing account balances, balance changes, values, value changes and -more, during one time period or many. Generally it shows a table, with -rows representing accounts, and columns representing periods. - - Note there are some variants of the 'balance' command with convenient -defaults, which are 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 modes:: -* Budget report:: -* Balance report layout:: -* Balance report output:: -* Some useful balance reports:: - - -File: hledger.info, Node: balance features, Next: Simple balance report, Up: balance - -29.1.1 balance features ------------------------ - -Here's a quick overview of the 'balance' command's features, followed by -more detailed descriptions and examples. Many of these work with the -other balance-like commands as well ('bs', 'cf', 'is'..). - - 'balance' can show.. - - * accounts as a list ('-l') or a tree ('-t') - * optionally depth-limited ('-[1-9]') - * sorted by declaration order and name, or by amount - - ..and their.. - - * balance changes (the default) - * or actual and planned balance changes ('--budget') - * or value of balance changes ('-V') - * or change of balance values ('--valuechange') - * or unrealised capital gain/loss ('--gain') - * or balance changes from sibling postings ('--related'/'-r') - * or postings count ('--count') - - ..in.. - - * one time period (the whole journal period by default) - * or multiple periods ('-D', '-W', '-M', '-Q', '-Y', '-p INTERVAL') - - ..either.. - - * per period (the default) - * or accumulated since report start date ('--cumulative') - * or accumulated since account creation ('--historical/-H') - - ..possibly converted to.. - - * cost ('--value=cost[,COMM]'/'--cost'/'-B') - * or market value, as of transaction dates ('--value=then[,COMM]') - * or at period ends ('--value=end[,COMM]') - * or now ('--value=now') - * or at some other date ('--value=YYYY-MM-DD') - - ..with.. - - * totals ('-T'), averages ('-A'), percentages ('-%'), inverted sign - ('--invert') - * rows and columns swapped ('--transpose') - * another field used as account name ('--pivot') - * custom-formatted line items (single-period reports only) - ('--format') - * commodities displayed on the same line or multiple lines - ('--layout') - - This command supports the output destination and output format -options, with output formats 'txt', 'csv', 'tsv' (_Added in 1.32_), -'json', and (multi-period reports only:) 'html', 'fods' (_Added in -1.40_). In 'txt' output in a colour-supporting terminal, negative -amounts are shown in red. - - -File: hledger.info, Node: Simple balance report, Next: Balance report line format, Prev: balance features, Up: balance - -29.1.2 Simple balance report ----------------------------- - -With no arguments, 'balance' shows a list of all accounts and their -change of balance - ie, the sum of posting amounts, both inflows and -outflows - during the entire period of the journal. ("Simple" here -means just one column of numbers, covering a single period. You can -also have multi-period reports, described later.) - - For real-world accounts, these numbers will normally be their end -balance at the end of the journal period; more on this below. - - Accounts are sorted by declaration order if any, and then -alphabetically by account name. For instance (using -examples/sample.journal): - -$ hledger -f examples/sample.journal bal - $1 assets:bank:saving - $-2 assets:cash - $1 expenses:food - $1 expenses:supplies - $-1 income:gifts - $-1 income:salary - $1 liabilities:debts --------------------- - 0 - - Accounts with a zero balance (and no non-zero subaccounts, in tree -mode - see below) are hidden by default. Use '-E/--empty' to show them -(revealing 'assets:bank:checking' here): - -$ hledger -f examples/sample.journal bal -E - 0 assets:bank:checking - $1 assets:bank:saving - $-2 assets:cash - $1 expenses:food - $1 expenses:supplies - $-1 income:gifts - $-1 income:salary - $1 liabilities:debts --------------------- - 0 - - The total of the amounts displayed is shown as the last line, unless -'-N'/'--no-total' is used. - - -File: hledger.info, Node: Balance report line format, Next: Filtered balance report, Prev: Simple balance report, Up: balance - -29.1.3 Balance report line format ---------------------------------- - -For single-period balance reports displayed in the terminal (only), you -can use '--format FMT' to customise the format and content of each line. -Eg: - -$ hledger -f examples/sample.journal balance --format "%20(account) %12(total)" - assets $-1 - bank:saving $1 - cash $-2 - expenses $2 - food $1 - supplies $1 - income $-2 - gifts $-1 - salary $-1 - liabilities:debts $1 ---------------------------------- - 0 - - The FMT format string specifies the formatting applied to each -account/balance pair. It may contain any suitable text, with data -fields interpolated like so: - - '%[MIN][.MAX](FIELDNAME)' - - * MIN pads with spaces to at least this width (optional) - - * MAX truncates at this width (optional) - - * FIELDNAME must be enclosed in parentheses, and can be one of: - - * 'depth_spacer' - a number of spaces equal to the account's - depth, or if MIN is specified, MIN * depth spaces. - * 'account' - the account's name - * 'total' - the account's balance/posted total, right justified - - Also, FMT can begin with an optional prefix to control how -multi-commodity amounts are rendered: - - * '%_' - render on multiple lines, bottom-aligned (the default) - * '%^' - render on multiple lines, top-aligned - * '%,' - render on one line, comma-separated - - There are some quirks. Eg in one-line mode, '%(depth_spacer)' has no -effect, instead '%(account)' has indentation built in. Experimentation -may be needed to get pleasing results. - - Some example formats: - - * '%(total)' - the account's total - * '%-20.20(account)' - the account's name, left justified, padded to - 20 characters and clipped at 20 characters - * '%,%-50(account) %25(total)' - account name padded to 50 - characters, total padded to 20 characters, with multiple - commodities rendered on one line - * '%20(total) %2(depth_spacer)%-(account)' - the default format for - the single-column balance report - - -File: hledger.info, Node: Filtered balance report, Next: List or tree mode, Prev: Balance report line format, Up: balance - -29.1.4 Filtered balance report ------------------------------- - -You can show fewer accounts, a different time period, totals from -cleared transactions only, etc. by using query arguments or options to -limit the postings being matched. Eg: - -$ hledger -f examples/sample.journal bal --cleared assets date:200806 - $-2 assets:cash --------------------- - $-2 - - -File: hledger.info, Node: List or tree mode, Next: Depth limiting, Prev: Filtered balance report, Up: balance - -29.1.5 List or tree mode ------------------------- - -By default, or with '-l/--flat', accounts are shown as a flat list with -their full names visible, as in the examples above. - - With '-t/--tree', the account hierarchy is shown, with subaccounts' -"leaf" names indented below their parent: - -$ hledger -f examples/sample.journal balance - $-1 assets - $1 bank:saving - $-2 cash - $2 expenses - $1 food - $1 supplies - $-2 income - $-1 gifts - $-1 salary - $1 liabilities:debts --------------------- - 0 - - Notes: - - * "Boring" accounts are combined with their subaccount for more - compact output, unless '--no-elide' is used. Boring accounts have - no balance of their own and just one subaccount (eg 'assets:bank' - and 'liabilities' above). - - * All balances shown are "inclusive", ie including the balances from - all subaccounts. Note this means some repetition in the output, - which requires explanation when sharing reports with - non-plaintextaccounting-users. A tree mode report's final total is - the sum of the top-level balances shown, not of all the balances - shown. - - * Each group of sibling accounts (ie, under a common parent) is - sorted separately. - - -File: hledger.info, Node: Depth limiting, Next: Dropping top-level accounts, Prev: List or tree mode, Up: balance - -29.1.6 Depth limiting ---------------------- - -With a 'depth:NUM' query, or '--depth NUM' option, or just '-NUM' (eg: -'-3') balance reports will show accounts only to the specified depth, -hiding the deeper subaccounts. This can be useful for getting an -overview without too much detail. - - Account balances at the depth limit always include the balances from -any deeper subaccounts (even in list mode). Eg, limiting to depth 1: - -$ hledger -f examples/sample.journal balance -1 - $-1 assets - $2 expenses - $-2 income - $1 liabilities --------------------- - 0 - - -File: hledger.info, Node: Dropping top-level accounts, Next: Showing declared accounts, Prev: Depth limiting, Up: balance - -29.1.7 Dropping top-level accounts ----------------------------------- - -You can also hide one or more top-level account name parts, using -'--drop NUM'. This can be useful for hiding repetitive top-level -account names: - -$ hledger -f examples/sample.journal bal expenses --drop 1 - $1 food - $1 supplies --------------------- - $2 - - -File: hledger.info, Node: Showing declared accounts, Next: Sorting by amount, Prev: Dropping top-level accounts, Up: balance - -29.1.8 Showing declared accounts --------------------------------- - -With '--declared', accounts which have been declared with an account -directive will be included in the balance report, even if they have no -transactions. (Since they will have a zero balance, you will also need -'-E/--empty' to see them.) - - More precisely, _leaf_ declared accounts (with no subaccounts) will -be included, since those are usually the more useful in reports. - - The idea of this is to be able to see a useful "complete" balance -report, even when you don't have transactions in all of your declared -accounts yet. - - -File: hledger.info, Node: Sorting by amount, Next: Percentages, Prev: Showing declared accounts, Up: balance - -29.1.9 Sorting by amount ------------------------- - -With '-S/--sort-amount', accounts with the largest (most positive) -balances are shown first. Eg: 'hledger bal expenses -MAS' shows your -biggest averaged monthly expenses first. When more than one commodity -is present, they will be sorted by the alphabetically earliest commodity -first, and then by subsequent commodities (if an amount is missing a -commodity, it is treated as 0). - - Revenues and liability balances are typically negative, however, so -'-S' shows these in reverse order. To work around this, you can add -'--invert' to flip the signs. Or you could use one of the higher-level -balance reports ('bs', 'is'..), which flip the sign automatically (eg: -'hledger is -MAS'). - - -File: hledger.info, Node: Percentages, Next: Multi-period balance report, Prev: Sorting by amount, Up: balance - -29.1.10 Percentages -------------------- - -With '-%/--percent', balance reports show each account's value expressed -as a percentage of the (column) total. - - Note it is not useful to calculate percentages if the amounts in a -column have mixed signs. In this case, make a separate report for each -sign, eg: - -$ hledger bal -% amt:`>0` -$ hledger bal -% amt:`<0` - - Similarly, if the amounts in a column have mixed commodities, convert -them to one commodity with '-B', '-V', '-X' or '--value', or make a -separate report for each commodity: - -$ hledger bal -% cur:\\$ -$ hledger bal -% cur:€ - - -File: hledger.info, Node: Multi-period balance report, Next: Balance change end balance, Prev: Percentages, Up: balance - -29.1.11 Multi-period balance report ------------------------------------ - -With a report interval (set by the '-D/--daily', '-W/--weekly', -'-M/--monthly', '-Q/--quarterly', '-Y/--yearly', or '-p/--period' flag), -'balance' shows a tabular report, with columns representing successive -time periods (and a title): - -$ hledger -f examples/sample.journal bal --quarterly income expenses -E -Balance changes in 2008: - - || 2008q1 2008q2 2008q3 2008q4 -===================++================================= - expenses:food || 0 $1 0 0 - expenses:supplies || 0 $1 0 0 - income:gifts || 0 $-1 0 0 - income:salary || $-1 0 0 0 --------------------++--------------------------------- - || $-1 $1 0 0 - - Notes: - - * The report's start/end dates will be expanded, if necessary, to - fully encompass the displayed subperiods (so that the first and - last subperiods have the same duration as the others). - * Leading and trailing periods (columns) containing all zeroes are - not shown, unless '-E/--empty' is used. - * Accounts (rows) containing all zeroes are not shown, unless - '-E/--empty' is used. - * Amounts with many commodities are shown in abbreviated form, unless - '--no-elide' is used. - * Average and/or total columns can be added with the '-A/--average' - and '-T/--row-total' flags. - * The '--transpose' flag can be used to exchange rows and columns. - * The '--pivot FIELD' option causes a different transaction field to - be used as "account name". See PIVOTING. - * The '--summary-only' flag ('--summary' also works) hides all but - the Total and Average columns (those should be enabled with - '--row-total' and '-A/--average'). - - Multi-period reports with many periods can be too wide for easy -viewing in the terminal. Here are some ways to handle that: - - * Hide the totals row with '-N/--no-total' - * Filter to a single currency with 'cur:' - * Convert to a single currency with '-V [--infer-market-price]' - * Use a more compact layout like '--layout=bare' - * Maximize the terminal window - * Reduce the terminal's font size - * View with a pager like less, eg: 'hledger bal -D --color=yes | less - -RS' - * Output as CSV and use a CSV viewer like visidata ('hledger bal -D - -O csv | vd -f csv'), Emacs' csv-mode ('M-x csv-mode, C-c C-a'), or - a spreadsheet ('hledger bal -D -o a.csv && open a.csv') - * Output as HTML and view with a browser: 'hledger bal -D -o a.html - && open a.html' - - -File: hledger.info, Node: Balance change end balance, Next: Balance report modes, Prev: Multi-period balance report, Up: balance - -29.1.12 Balance change, end balance ------------------------------------ - -It's important to be clear on the meaning of the numbers shown in -balance reports. Here is some terminology we use: - - A *_balance change_* is the net amount added to, or removed from, an -account during some period. - - An *_end balance_* is the amount accumulated in an account as of some -date (and some time, but hledger doesn't store that; assume end of day -in your timezone). It is the sum of previous balance changes. - - We call it a *_historical end balance_* if it includes all balance -changes since the account was created. For a real world account, this -means it will match the "historical record", eg the balances reported in -your bank statements or bank web UI. (If they are correct!) - - In general, balance changes are what you want to see when reviewing -revenues and expenses, and historical end balances are what you want to -see when reviewing or reconciling asset, liability and equity accounts. - - 'balance' shows balance changes by default. To see accurate -historical end balances: - - 1. Initialise account starting balances with an "opening balances" - transaction (a transfer from equity to the account), unless the - journal covers the account's full lifetime. - - 2. Include all of of the account's prior postings in the report, by - not specifying a report start date, or by using the - '-H/--historical' flag. ('-H' causes report start date to be - ignored when summing postings.) - - -File: hledger.info, Node: Balance report modes, Next: Budget report, Prev: Balance change end balance, Up: balance - -29.1.13 Balance report modes ----------------------------- - -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 [CALCULATIONMODE] [ACCUMULATIONMODE] [VALUATIONMODE] -...' - -* Menu: - -* Calculation mode:: -* Accumulation mode:: -* Valuation mode:: -* Combining balance report modes:: - - -File: hledger.info, Node: Calculation mode, Next: Accumulation mode, Up: Balance report modes - -29.1.13.1 Calculation mode -.......................... - -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 mode, Next: Valuation mode, Prev: Calculation mode, Up: Balance report modes - -29.1.13.2 Accumulation mode -........................... - -How amounts should accumulate across a report's subperiods/columns. -Another way to say it: which time period's postings should contribute to -each cell's calculation. It is one of: - - * '--change' : calculate with postings from column start to column - end, ie "just this column". Typically used to see - revenues/expenses. (*default for balance, cashflow, - incomestatement*) - - * '--cumulative' : calculate with postings from report start to - column end, ie "previous columns plus this column". Typically used - to show changes accumulated since the report's start date. Not - often used. - - * '--historical/-H' : calculate with postings from journal start to - column end, ie "all postings from before report start date until - this column's end". Typically used to see historical end balances - of assets/liabilities/equity. (*default for balancesheet, - balancesheetequity*) - - -File: hledger.info, Node: Valuation mode, Next: Combining balance report modes, Prev: Accumulation mode, Up: Balance report modes - -29.1.13.3 Valuation mode -........................ - -Which kind of value or cost conversion should be applied, if any, before -displaying the report. See Cost reporting and Value reporting for more -about conversions. - - A valuation (or cost) mode can be selected with the -value option: - - * no conversion : 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 with the legacy -B/-V/-X options, which are equivalent and easier -to type: - - * '-B'/'--cost' : like -value=cost - * '-V'/'--market' : like -value=end - * '-X COMM'/'--exchange COMM' : like -value=end,COMM - - Note that -value can also convert to cost, as a convenience; but -actually -cost and -value are independent options, and could be used -together. - - -File: hledger.info, Node: Combining balance report modes, Prev: Valuation mode, Up: Balance report modes - -29.1.13.4 Combining balance report modes -........................................ - -Most combinations of these modes 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 modes, Up: balance - -29.1.14 Budget report ---------------------- - -The '--budget' report is like a regular balance report, but with two -main differences: - - * Budget goals and performance percentages are also shown, in - brackets - * Accounts which don't have budget goals are hidden by default. - - This is useful for comparing planned and actual income, expenses, -time usage, etc. - - Periodic transaction rules are used to define budget goals. For -example, here's a periodic rule defining monthly goals for bus travel -and food expenses: - -;; Budget -~ monthly - (expenses:bus) $30 - (expenses:food) $400 - - After recording some actual expenses, - -;; Two months worth of expenses -2017-11-01 - income $-1950 - expenses:bus $35 - expenses:food:groceries $310 - expenses:food:dining $42 - expenses:movies $38 - assets:bank:checking - -2017-12-01 - income $-2100 - expenses:bus $53 - expenses:food:groceries $380 - expenses:food:dining $32 - expenses:gifts $100 - assets:bank:checking - - we can see a budget report like this: - -$ hledger bal -M --budget -Budget performance in 2017-11-01..2017-12-31: - - || Nov Dec -===============++============================================ - || $-425 $-565 - expenses || $425 [ 99% of $430] $565 [131% of $430] - expenses:bus || $35 [117% of $30] $53 [177% of $30] - expenses:food || $352 [ 88% of $400] $412 [103% of $400] ----------------++-------------------------------------------- - || 0 [ 0% of $430] 0 [ 0% of $430] - - This is "goal-based budgeting"; you define goals for accounts and -periods, often recurring, and hledger shows performance relative to the -goals. This contrasts with "envelope budgeting", which is more detailed -and strict - useful when cash is tight, but also quite a bit more work. -https://plaintextaccounting.org/Budgeting has more on this topic. - -* Menu: - -* Using the budget report:: -* Budget date surprises:: -* Selecting budget goals:: -* Budgeting vs forecasting:: - - -File: hledger.info, Node: Using the budget report, Next: Budget date surprises, Up: Budget report - -29.1.14.1 Using the budget report -................................. - -Historically this report has been confusing and fragile. hledger's -version should be relatively robust and intuitive, but you may still -find surprises. Here are more notes to help with learning and -troubleshooting. - - * In the above example, 'expenses:bus' and 'expenses:food' are shown - because they have budget goals during the report period. - - * Their parent 'expenses' is also shown, with budget goals aggregated - from the children. - - * The subaccounts 'expenses:food:groceries' and - 'expenses:food:dining' are not shown since they have no budget goal - of their own, but they contribute to 'expenses:food''s actual - amount. - - * Unbudgeted accounts 'expenses:movies' and 'expenses:gifts' are also - not shown, but they contribute to 'expenses''s actual amount. - - * The other unbudgeted accounts 'income' and 'assets:bank:checking' - are grouped as ''. - - * '--depth' or 'depth:' can be used to limit report depth in the - usual way (but will not reveal unbudgeted subaccounts). - - * Amounts are always inclusive of subaccounts (even in '-l/--list' - mode). - - * Numbers displayed in a -budget report will not always agree with - the totals, because of hidden unbudgeted accounts; this is normal. - '-E/--empty' can be used to reveal the hidden accounts. - - * In the periodic rules used for setting budget goals, unbalanced - postings are convenient. - - * You can filter budget reports with the usual queries, eg to focus - on particular accounts. It's common to restrict them to just - expenses. (The '' account is occasionally hard to - exclude; this is because of date surprises, discussed below.) - - * When you have multiple currencies, you may want to convert them to - one ('-X COMM --infer-market-prices') and/or show just one at a - time ('cur:COMM'). If you do need to show multiple currencies at - once, '--layout bare' can be helpful. - - * You can "roll over" amounts (actual and budgeted) to the next - period with '--cumulative'. - - See also: https://hledger.org/budgeting.html. - - -File: hledger.info, Node: Budget date surprises, Next: Selecting budget goals, Prev: Using the budget report, Up: Budget report - -29.1.14.2 Budget date surprises -............................... - -With small data, or when starting out, some of the generated budget goal -transaction dates might fall outside the report periods. Eg with the -following journal and report, the first period appears to have no -'expenses:food' budget. (Also the '' account should be -excluded by the 'expenses' query, but isn't.): - -~ monthly in 2020 - (expenses:food) $500 - -2020-01-15 - expenses:food $400 - assets:checking - -$ hledger bal --budget expenses -Budget performance in 2020-01-15: - - || 2020-01-15 -===============++==================== - || $400 - expenses:food || 0 [ 0% of $500] ----------------++-------------------- - || $400 [80% of $500] - - In this case, the budget goal transactions are generated on first -days of of month (this can be seen with 'hledger print --forecast -tag:generated expenses'). Whereas the report period defaults to just -the 15th day of january (this can be seen from the report table's column -headings). - - To fix this kind of thing, be more explicit about the report period -(and/or the periodic rules' dates). In this case, adding '-b 2020' does -the trick. - - -File: hledger.info, Node: Selecting budget goals, Next: Budgeting vs forecasting, Prev: Budget date surprises, Up: Budget report - -29.1.14.3 Selecting budget goals -................................ - -By default, the budget report uses all available periodic transaction -rules to generate goals. This includes rules with a different report -interval from your report. Eg if you have daily, weekly and monthly -periodic rules, all of these will contribute to the goals in a monthly -budget report. - - You can select a subset of periodic rules by providing an argument to -the '--budget' flag. '--budget=DESCPAT' will match all periodic rules -whose description contains DESCPAT, a case-insensitive substring (not a -regular expression or query). This means you can give your periodic -rules descriptions (remember that two spaces are needed between period -expression and description), and then select from multiple budgets -defined in your journal. - - -File: hledger.info, Node: Budgeting vs forecasting, Prev: Selecting budget goals, Up: Budget report - -29.1.14.4 Budgeting vs forecasting -.................................. - -'--forecast' and '--budget' both use the periodic transaction rules in -the journal to generate temporary transactions for reporting purposes. -However they are separate features - though you can use both at the same -time if you want. Here are some differences between them: - --forecast -budget --------------------------------------------------------------------------- -is a general option; it enables is a balance command option; -forecasting with all reports it selects the balance - report's budget mode -generates visible transactions which generates invisible -appear in reports transactions which produce - goal amounts -generates forecast transactions from generates budget goal -after the last regular transaction, to transactions throughout the -the end of the report period; or with report period, optionally -an argument '--forecast=PERIODEXPR' restricted by periods -generates them throughout the specified in the periodic -specified period, both optionally transaction rules -restricted by periods specified in the -periodic transaction rules -uses all periodic rules uses all periodic rules; or - with an argument - '--budget=DESCPAT' uses just - the rules matched by DESCPAT - - -File: hledger.info, Node: Balance report layout, Next: Balance report output, Prev: Budget report, Up: balance - -29.1.15 Balance report layout ------------------------------ - -The '--layout' option affects how 'balance' and the other balance-like -commands show multi-commodity amounts and commodity symbols. It can -improve readability, for humans and/or machines (other software). It -has four possible values: - - * '--layout=wide[,WIDTH]': commodities are shown on a single line, - optionally elided to WIDTH - * '--layout=tall': each commodity is shown on a separate line - * '--layout=bare': commodity symbols are in their own column, amounts - are bare numbers - * '--layout=tidy': data is normalised to easily-consumed "tidy" form, - with one row per data value. (This one is currently supported only - by the 'balance' command.) - - Here are the '--layout' modes supported by each output format Only -CSV output supports all of them: - -- txt csv html json sql ---------------------------------------- -wide Y Y Y -tall Y Y Y -bare Y Y Y -tidy Y - - Examples: - -* Menu: - -* Wide layout:: -* Tall layout:: -* Bare layout:: -* Tidy layout:: - - -File: hledger.info, Node: Wide layout, Next: Tall layout, Up: Balance report layout - -29.1.15.1 Wide layout -..................... - -With many commodities, reports can be very wide: - -$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide -Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total -==================++==================================================================================================================================================================================================================== - Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT -------------------++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- - || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT - - A width limit reduces the width, but some commodities will be hidden: - -$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32 -Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total -==================++=========================================================================================================================== - Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. -------------------++--------------------------------------------------------------------------------------------------------------------------- - || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. - - -File: hledger.info, Node: Tall layout, Next: Bare layout, Prev: Wide layout, Up: Balance report layout - -29.1.15.2 Tall layout -..................... - -Each commodity gets a new line (may be different in each column), and -account names are repeated: - -$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall -Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total -==================++================================================== - Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - Assets:US:ETrade || 18.00 VHT 294.00 VHT -------------------++-------------------------------------------------- - || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - || 18.00 VHT 294.00 VHT - - -File: hledger.info, Node: Bare layout, Next: Tidy layout, Prev: Tall layout, Up: Balance report layout - -29.1.15.3 Bare layout -..................... - -Commodity symbols are kept in one column, each commodity has its own -row, amounts are bare numbers, account names are repeated: - -$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare -Balance changes in 2012-01-01..2014-12-31: - - || Commodity 2012 2013 2014 Total -==================++============================================= - Assets:US:ETrade || GLD 0 70.00 0 70.00 - Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 - Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 - Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 - Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 -------------------++--------------------------------------------- - || GLD 0 70.00 0 70.00 - || ITOT 10.00 18.00 -11.00 17.00 - || USD 337.18 -98.12 4881.44 5120.50 - || VEA 12.00 10.00 14.00 36.00 - || VHT 106.00 18.00 170.00 294.00 - - Bare layout also affects CSV output, which is useful for producing -data that is easier to consume, eg for making charts: - -$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare -"account","commodity","balance" -"Assets:US:ETrade","GLD","70.00" -"Assets:US:ETrade","ITOT","17.00" -"Assets:US:ETrade","USD","5120.50" -"Assets:US:ETrade","VEA","36.00" -"Assets:US:ETrade","VHT","294.00" -"Total:","GLD","70.00" -"Total:","ITOT","17.00" -"Total:","USD","5120.50" -"Total:","VEA","36.00" -"Total:","VHT","294.00" - - Bare layout will sometimes display an extra row for the no-symbol -commodity, because of zero amounts (hledger treats zeroes as -commodity-less, usually). This can break 'hledger-bar' confusingly -(workaround: add a 'cur:' query to exclude the no-symbol row). - - -File: hledger.info, Node: Tidy layout, Prev: Bare layout, Up: Balance report layout - -29.1.15.4 Tidy layout -..................... - -This produces normalised "tidy data" (see -https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html) -where every variable has its own column and each row represents a single -data point. This is the easiest kind of data for other software to -consume: - -$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy -"account","period","start_date","end_date","commodity","value" -"Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" -"Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" -"Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" -"Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" -"Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" -"Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" -"Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" -"Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" -"Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" -"Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" -"Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" -"Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" -"Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" -"Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" -"Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" - - -File: hledger.info, Node: Balance report output, Next: Some useful balance reports, Prev: Balance report layout, Up: balance - -29.1.16 Balance report output ------------------------------ - -As noted in Output format, if you choose HTML output (by using '-O html' -or '-o somefile.html'), you can create a 'hledger.css' file in the same -directory to customise the report's appearance. - - The HTML and FODS output formats can generate hyperlinks to a -'hledger-web' register view for each account and period. E.g. if your -'hledger-web' server is reachable at 'http://localhost:5000' then you -might run the 'balance' command with the extra option -'--base-url=http://localhost:5000'. You can also produce relative -links, like '--base-url="some/path"' or '--base-url=""'.) - - -File: hledger.info, Node: Some useful balance reports, Prev: Balance report output, Up: balance - -29.1.17 Some useful balance reports ------------------------------------ - -Some frequently used 'balance' options/reports are: - - * 'bal -M revenues expenses' - Show revenues/expenses in each month. Also available as the - 'incomestatement' command. - - * 'bal -M -H assets liabilities' - Show historical asset/liability balances at each month end. Also - available as the 'balancesheet' command. - - * 'bal -M -H assets liabilities equity' - Show historical asset/liability/equity balances at each month end. - Also available as the 'balancesheetequity' command. - - * 'bal -M assets not:receivable' - Show changes to liquid assets in each month. Also available as the - 'cashflow' command. - - Also: - - * 'bal -M expenses -2 -SA' - Show monthly expenses summarised to depth 2 and sorted by average - amount. - - * 'bal -M --budget expenses' - Show monthly expenses and budget goals. - - * 'bal -M --valuechange investments' - Show monthly change in market value of investment assets. - - * 'bal investments --valuechange -D date:lastweek amt:'>1000' -STA - [--invert]' - Show top gainers [or losers] last week - - -File: hledger.info, Node: roi, Prev: balance, Up: Advanced report commands - -29.2 roi -======== - -Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on -your investments. - -Flags: - --cashflow show all amounts that were used to compute - returns - --investment=QUERY query to select your investment transactions - --profit-loss=QUERY --pnl query to select profit-and-loss or - appreciation/valuation transactions - - At a minimum, you need to supply a query (which could be just an -account name) to select your investment(s) with '--inv', and another -query to identify your profit and loss transactions with '--pnl'. - - If you do not record changes in the value of your investment -manually, or do not require computation of time-weighted return (TWR), -'--pnl' could be an empty query ('--pnl ""' or '--pnl STR' where 'STR' -does not match any of your accounts). - - This command will compute and display the internalized rate of return -(IRR, also known as money-weighted rate of return) and time-weighted -rate of return (TWR) for your investments for the time period requested. -IRR is always annualized due to the way it is computed, but TWR is -reported both as a rate over the chosen reporting period and as an -annual rate. - - Price directives will be taken into account if you supply appropriate -'--cost' or '--value' flags (see VALUATION). - - Note, in some cases this report can fail, for these reasons: - - * Error (NotBracketed): No solution for Internal Rate of Return - (IRR). Possible causes: IRR is huge (>1000000%), balance of - investment becomes negative at some point in time. - * Error (SearchFailed): Failed to find solution for Internal Rate of - Return (IRR). Either search does not converge to a solution, or - converges too slowly. - - Examples: - - * Using roi to compute total return of investment in stocks: - https://github.com/simonmichael/hledger/blob/master/examples/investing/roi-unrealised.ledger - - * Cookbook > Return on Investment: https://hledger.org/roi.html - -* Menu: - -* Spaces and special characters in --inv and --pnl:: -* Semantics of --inv and --pnl:: -* IRR and TWR explained:: - - -File: hledger.info, Node: Spaces and special characters in --inv and --pnl, Next: Semantics of --inv and --pnl, Up: roi - -29.2.1 Spaces and special characters in '--inv' and ---------------------------------------------------- - -'--pnl' Note that '--inv' and '--pnl''s argument is a query, and queries -could have several space-separated terms (see QUERIES). - - To indicate that all search terms form single command-line argument, -you will need to put them in quotes (see Special characters): - -$ hledger roi --inv 'term1 term2 term3 ...' - - If any query terms contain spaces themselves, you will need an extra -level of nested quoting, eg: - -$ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'" - - -File: hledger.info, Node: Semantics of --inv and --pnl, Next: IRR and TWR explained, Prev: Spaces and special characters in --inv and --pnl, Up: roi - -29.2.2 Semantics of '--inv' and '--pnl' ---------------------------------------- - -Query supplied to '--inv' has to match all transactions that are related -to your investment. Transactions not matching '--inv' will be ignored. - - In these transactions, ROI will conside postings that match '--inv' -to be "investment postings" and other postings (not matching '--inv') -will be sorted into two categories: "cash flow" and "profit and loss", -as ROI needs to know which part of the investment value is your -contributions and which is due to the return on investment. - - * "Cash flow" is depositing or withdrawing money, buying or selling - assets, or otherwise converting between your investment commodity - and any other commodity. Example: - - 2019-01-01 Investing in Snake Oil - assets:cash -$100 - investment:snake oil - - 2020-01-01 Selling my Snake Oil - assets:cash $10 - investment:snake oil = 0 - - * "Profit and loss" is change in the value of your investment: - - 2019-06-01 Snake Oil falls in value - investment:snake oil = $57 - equity:unrealized profit or loss - - All non-investment postings are assumed to be "cash flow", unless -they match '--pnl' query. Changes in value of your investment due to -"profit and loss" postings will be considered as part of your investment -return. - - Example: if you use '--inv snake --pnl equity:unrealized', then -postings in the example below would be classifed as: - -2019-01-01 Snake Oil #1 - assets:cash -$100 ; cash flow posting - investment:snake oil ; investment posting - -2019-03-01 Snake Oil #2 - equity:unrealized pnl -$100 ; profit and loss posting - snake oil ; investment posting - -2019-07-01 Snake Oil #3 - equity:unrealized pnl ; profit and loss posting - cash -$100 ; cash flow posting - snake oil $50 ; investment posting - - -File: hledger.info, Node: IRR and TWR explained, Prev: Semantics of --inv and --pnl, Up: roi - -29.2.3 IRR and TWR explained ----------------------------- - -"ROI" stands for "return on investment". Traditionally this was -computed as a difference between current value of investment and its -initial value, expressed in percentage of the initial value. - - However, this approach is only practical in simple cases, where -investments receives no in-flows or out-flows of money, and where rate -of growth is fixed over time. For more complex scenarios you need -different ways to compute rate of return, and this command implements -two of them: IRR and TWR. - - Internal rate of return, or "IRR" (also called "money-weighted rate -of return") takes into account effects of in-flows and out-flows, and -the time between them. Investment at a particular fixed interest rate -is going to give you more interest than the same amount invested at the -same interest rate, but made later in time. If you are withdrawing from -your investment, your future gains would be smaller (in absolute -numbers), and will be a smaller percentage of your initial investment, -so your IRR will be smaller. And if you are adding to your investment, -you will receive bigger absolute gains, which will be a bigger -percentage of your initial investment, so your IRR will be larger. - - As mentioned before, in-flows and out-flows would be any cash that -you personally put in or withdraw, and for the "roi" command, these are -the postings that match the query in the'--inv' argument and NOT match -the query in the'--pnl' argument. - - If you manually record changes in the value of your investment as -transactions that balance them against "profit and loss" (or "unrealized -gains") account or use price directives, then in order for IRR to -compute the precise effect of your in-flows and out-flows on the rate of -return, you will need to record the value of your investement on or -close to the days when in- or out-flows occur. - - In technical terms, IRR uses the same approach as computation of net -present value, and tries to find a discount rate that makes net present -value of all the cash flows of your investment to add up to zero. This -could be hard to wrap your head around, especially if you haven't done -discounted cash flow analysis before. Implementation of IRR in hledger -should produce results that match the '=XIRR' formula in Excel. - - Second way to compute rate of return that 'roi' command implements is -called "time-weighted rate of return" or "TWR". Like IRR, it will -account for the effect of your in-flows and out-flows, but unlike IRR it -will try to compute the true rate of return of the underlying asset, -compensating for the effect that deposits and withdrawas have on the -apparent rate of growth of your investment. - - TWR represents your investment as an imaginary "unit fund" where -in-flows/ out-flows lead to buying or selling "units" of your investment -and changes in its value change the value of "investment unit". Change -in "unit price" over the reporting period gives you rate of return of -your investment, and make TWR less sensitive than IRR to the effects of -cash in-flows and out-flows. - - References: - - * Explanation of rate of return - * Explanation of IRR - * Explanation of TWR - * IRR vs TWR - * Examples of computing IRR and TWR and discussion of the limitations - of both metrics - - -File: hledger.info, Node: Chart commands, Next: Data generation commands, Prev: Advanced report commands, Up: Top - -30 Chart commands -***************** - -* Menu: - -* activity:: - - -File: hledger.info, Node: activity, Up: Chart commands - -30.1 activity -============= - -Show an ascii barchart of posting counts per interval. - -Flags: -no command-specific flags - - The activity command displays an ascii histogram showing transaction -counts by day, week, month or other reporting interval (by day is the -default). With query arguments, it counts only matched transactions. - - Examples: - -$ hledger activity --quarterly -2008-01-01 ** -2008-04-01 ******* -2008-07-01 -2008-10-01 ** - - -File: hledger.info, Node: Data generation commands, Next: Maintenance commands, Prev: Chart commands, Up: Top - -31 Data generation commands -*************************** - -* Menu: - -* close:: -* rewrite:: - - -File: hledger.info, Node: close, Next: rewrite, Up: Data generation commands - -31.1 close -========== - -(equity) - - 'close' prints several kinds of "closing" and/or "opening" -transactions, useful in various situations: migrating balances to a new -journal file, retaining earnings into equity, consolidating balances, -viewing lot costs.. Like 'print', it prints valid journal entries. You -can copy these into your journal file(s) when you are happy with how -they look. - -Flags: - --clopen[=TAGVAL] show closing and opening balances transactions, - for AL accounts by default - --close[=TAGVAL] show just a closing balances transaction - --open[=TAGVAL] show just an opening balances transaction - --assert[=TAGVAL] show a balance assertions transaction - --assign[=TAGVAL] show a balance assignments transaction - --retain[=TAGVAL] show a retain earnings transaction, for RX - accounts by default - -x --explicit show all amounts explicitly - --show-costs show amounts with different costs separately - --interleaved show source and destination postings together - --assertion-type=TYPE =, ==, =* or ==* - --close-desc=DESC set closing transaction's description - --close-acct=ACCT set closing transaction's destination account - --open-desc=DESC set opening transaction's description - --open-acct=ACCT set opening transaction's source account - --round=TYPE how much rounding or padding should be done when - displaying amounts ? - none - show original decimal digits, - as in journal (default) - soft - just add or remove decimal zeros - to match precision - hard - round posting amounts to precision - (can unbalance transactions) - all - also round cost amounts to precision - (can unbalance transactions) - - 'close' has six modes, selected by choosing one of the mode flags -('--close' is the default). They all do much the same operation, but -with different defaults, useful in different situations. - -* Menu: - -* close --clopen:: -* close --close:: -* close --open:: -* close --assert:: -* close --assign:: -* close --retain:: -* close customisation:: -* close and balance assertions:: -* close examples:: - - -File: hledger.info, Node: close --clopen, Next: close --close, Up: close - -31.1.1 close -clopen --------------------- - -This is useful if migrating balances to a new journal file at the start -of a new year. It prints a "closing balances" transaction that zeroes -out account balances (Asset and Liability accounts, by default), and an -opposite "opening balances" transaction that restores them again. -Typically, you would run - -hledger close --clopen -e NEWYEAR >> $LEDGER_FILE - - and then move the opening transaction from the old file to the new -file (and probably also update your LEDGER_FILE environment variable). - - Why might you do this ? If your reports are fast, you may not need -it. But at some point you will probably want to partition your data by -time, for performance or data integrity or regulatory reasons. A new -file or set of files per year is common. Then, having each file/fileset -"bookended" with opening and closing balance transactions will allow you -to freely pick and choose which files to read - just the current year, -any past year, any sequence of years, or all of them - while showing -correct account balances in each case. The earliest opening balances -transaction sets correct starting balances, and any later -closing/opening pairs will harmlessly cancel each other out. - - The balances will be transferred to and from 'equity:opening/closing -balances' by default. You can override this by using '--close-acct' -and/or '--open-acct'. - - You can select a different set of accounts to close/open by providing -an account query. Eg to add Equity accounts, provide arguments like -'assets liabilities equity' or 'type:ALE'. When migrating to a new -file, you'll usually want to bring along the AL or ALE accounts, but not -the RX accounts (Revenue, Expense). - - Assertions will be added indicating and checking the new balances of -the closed/opened accounts. - - The generated transactions will have a 'clopen:' tag. If the main -journal's base file name contains a number (eg a year number), the tag's -value will be that base file name with the number incremented. Or you -can choose the tag value yourself, by using '--clopen=TAGVAL'. - - -File: hledger.info, Node: close --close, Next: close --open, Prev: close --clopen, Up: close - -31.1.2 close -close -------------------- - -This prints just the closing balances transaction of '--clopen'. It is -the default if you don't specify a mode. - - More customisation options are described below. Among other things, -you can use 'close --close' to generate a transaction moving the -balances from any set of accounts, to a different account. (If you need -to move just a portion of the balance, see hledger-move.) - - -File: hledger.info, Node: close --open, Next: close --assert, Prev: close --close, Up: close - -31.1.3 close -open ------------------- - -This prints just the opening balances transaction of '--clopen'. (It is -similar to Ledger's equity command.) - - -File: hledger.info, Node: close --assert, Next: close --assign, Prev: close --open, Up: close - -31.1.4 close -assert --------------------- - -This prints a transaction that asserts the account balances as they are -on the end date (and adds an 'assert:' tag). It could be useful as -documention and to guard against changes. - - -File: hledger.info, Node: close --assign, Next: close --retain, Prev: close --assert, Up: close - -31.1.5 close -assign --------------------- - -This prints a transaction that assigns the account balances as they are -on the end date (and adds an "assign:" tag). Unlike balance assertions, -assignments will post changes to balances as needed to reach the -specified amounts. - - This is another way to set starting balances when migrating to a new -file, and it will set them correctly even in the presence of earlier -files which do not have a closing balances transaction. However, it can -hide errors, and disturb the accounting equation, so '--clopen' is -usually recommended. - - -File: hledger.info, Node: close --retain, Next: close customisation, Prev: close --assign, Up: close - -31.1.6 close -retain --------------------- - -This is like '--close', but it closes Revenue and Expense account -balances by default. They will be transferred to 'equity:retained -earnings', or another account specified with '--close-acct'. - - Revenues and expenses correspond to changes in equity. They are -categorised separately for reporting purposes, but traditionally at the -end of each accounting period, businesses consolidate them into equity, -This is called "retaining earnings", or "closing the books". - - In personal accounting, there's not much reason to do this, and most -people don't. (One reason to do it is to help the 'balancesheetequity' -report show a zero total, demonstrating that the accounting equation -(A-L=E) is satisfied.) - - -File: hledger.info, Node: close customisation, Next: close and balance assertions, Prev: close --retain, Up: close - -31.1.7 close customisation --------------------------- - -In all modes, the following things can be overridden: - - * the accounts to be closed/opened, with account query arguments - * the balancing account, with '--close-acct=ACCT' and/or - '--open-acct=ACCT' - * the transaction descriptions, with '--close-desc=DESC' and - '--open-desc=DESC' - * the transaction's tag value, with a '--MODE=NEW' option argument - * the closing/opening dates, with '-e OPENDATE' - - By default, the closing date is yesterday, or the journal's end date, -whichever is later; and the opening date is always one day after the -closing date. You can change these by specifying a report end date; the -closing date will be the last day of the report period. Eg '-e 2024' -means "close on 2023-12-31, open on 2024-01-01". - - With '--x/--explicit', the balancing amount will be shown explicitly, -and if it involves multiple commodities, a separate posting will be -generated for each of them (similar to 'print -x'). - - With '--interleaved', each individual transfer is shown with source -and destination postings next to each other (perhaps useful for -troubleshooting). - - With '--show-costs', balances' costs are also shown, with different -costs kept separate. This may generate very large journal entries, if -you have many currency conversions or investment transactions. 'close ---show-costs' is currently the best way to view investment lots with -hledger. (To move or dispose of lots, see the more capable -'hledger-move' script.) - - -File: hledger.info, Node: close and balance assertions, Next: close examples, Prev: close customisation, Up: close - -31.1.8 close and balance assertions ------------------------------------ - -'close' adds balance assertions verifying that the accounts have been -reset to zero in a closing transaction or restored to their previous -balances in an opening transaction. These provide useful error -checking, but you can ignore them temporarily with '-I', or remove them -if you prefer. - - Single-commodity, subaccount-exclusive balance assertions ('=') are -generated by default. This can be changed with '--assertion-type='==*'' -(eg). - - When running 'close' you should probably avoid using '-C', '-R', -'status:' (filtering by status or realness) or '--auto' (generating -postings), since the generated balance assertions would then require -these. - - Transactions with multiple dates (eg posting dates) spanning the file -boundary also can disrupt the balance assertions: - -2023-12-30 a purchase made in december, cleared in january - expenses:food 5 - assets:bank:checking -5 ; date: 2023-01-02 - - To solve this you can transfer the money to and from a temporary -account, splitting the multi-day transaction into two single-day -transactions: - -; in 2022.journal: -2022-12-30 a purchase made in december, cleared in january - expenses:food 5 - equity:pending -5 - -; in 2023.journal: -2023-01-02 last year's transaction cleared - equity:pending 5 = 0 - assets:bank:checking -5 - - -File: hledger.info, Node: close examples, Prev: close and balance assertions, Up: close - -31.1.9 close examples ---------------------- - -* Menu: - -* Retain earnings:: -* Migrate balances to a new file:: -* More detailed close examples:: - - -File: hledger.info, Node: Retain earnings, Next: Migrate balances to a new file, Up: close examples - -31.1.9.1 Retain earnings -........................ - -Record 2022's revenues/expenses as retained earnings on 2022-12-31, -appending the generated transaction to the journal: - -$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal - - After this, to see 2022's revenues and expenses you must exclude the -retain earnings transaction: - -$ hledger -f 2022.journal is not:desc:'retain earnings' - - -File: hledger.info, Node: Migrate balances to a new file, Next: More detailed close examples, Prev: Retain earnings, Up: close examples - -31.1.9.2 Migrate balances to a new file -....................................... - -Close assets/liabilities on 2022-12-31 and re-open them on 2023-01-01: - -$ hledger close --clopen -f 2022.journal -p 2022 -# copy/paste the closing transaction to the end of 2022.journal -# copy/paste the opening transaction to the start of 2023.journal - - After this, to see 2022's end-of-year balances you must exclude the -closing balances transaction: - -$ hledger -f 2022.journal bs not:desc:'closing balances' - - For more flexibility, it helps to tag closing and opening -transactions with eg 'clopen:NEWYEAR', then you can ensure correct -balances by excluding all opening/closing transactions except the first, -like so: - -$ hledger bs -Y -f 2021.j -f 2022.j -f 2023.j expr:'tag:clopen=2021 or not tag:clopen' -$ hledger bs -Y -f 2021.j -f 2022.j expr:'tag:clopen=2021 or not tag:clopen' -$ hledger bs -Y -f 2022.j -f 2023.j expr:'tag:clopen=2022 or not tag:clopen' -$ hledger bs -Y -f 2021.j expr:'tag:clopen=2021 or not tag:clopen' -$ hledger bs -Y -f 2022.j expr:'tag:clopen=2022 or not tag:clopen' -$ hledger bs -Y -f 2023.j # unclosed file, no query needed - - -File: hledger.info, Node: More detailed close examples, Prev: Migrate balances to a new file, Up: close examples - -31.1.9.3 More detailed close examples -..................................... - -See examples/multi-year. - - -File: hledger.info, Node: rewrite, Prev: close, Up: Data generation commands - -31.2 rewrite -============ - -Print all transactions, rewriting the postings of matched transactions. -For now the only rewrite available is adding new postings, like print --auto. - -Flags: - --add-posting='ACCT AMTEXPR' add a posting to ACCT, which may be - parenthesised. AMTEXPR is either a literal - amount, or *N which means the transaction's - first matched amount multiplied by N (a - decimal number). Two spaces separate ACCT - and AMTEXPR. - --diff generate diff suitable as an input for - patch tool - - This is a start at a generic rewriter of transaction entries. It -reads the default journal and prints the transactions, like print, but -adds one or more specified postings to any transactions matching QUERY. -The posting amounts can be fixed, or a multiplier of the existing -transaction's first posting amount. - - Examples: - -$ hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100' -$ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"' -$ hledger-rewrite.hs -f rewrites.hledger - - rewrites.hledger may consist of entries like: - -= ^income amt:<0 date:2017 - (liabilities:tax) *0.33 ; tax on income - (reserve:grocery) *0.25 ; reserve 25% for grocery - (reserve:) *0.25 ; reserve 25% for grocery - - Note the single quotes to protect the dollar sign from bash, and the -two spaces between account and amount. - - More: - -$ hledger rewrite [QUERY] --add-posting "ACCT AMTEXPR" ... -$ hledger rewrite ^income --add-posting '(liabilities:tax) *.33' -$ hledger rewrite expenses:gifts --add-posting '(budget:gifts) *-1"' -$ hledger rewrite ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' - - Argument for '--add-posting' option is a usual posting of transaction -with an exception for amount specification. More precisely, you can use -''*'' (star symbol) before the amount to indicate that that this is a -factor for an amount of original matched posting. If the amount -includes a commodity name, the new posting amount will be in the new -commodity; otherwise, it will be in the matched posting amount's -commodity. - -* Menu: - -* Re-write rules in a file:: -* Diff output format:: -* rewrite vs print --auto:: - - -File: hledger.info, Node: Re-write rules in a file, Next: Diff output format, Up: rewrite - -31.2.1 Re-write rules in a file -------------------------------- - -During the run this tool will execute so called "Automated Transactions" -found in any journal it process. I.e instead of specifying this -operations in command line you can put them in a journal file. - -$ rewrite-rules.journal - - Make contents look like this: - -= ^income - (liabilities:tax) *.33 - -= expenses:gifts - budget:gifts *-1 - assets:budget *1 - - Note that ''='' (equality symbol) that is used instead of date in -transactions you usually write. It indicates the query by which you -want to match the posting to add new ones. - -$ hledger rewrite -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal - - This is something similar to the commands pipeline: - -$ hledger rewrite -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \ - | hledger rewrite -f - expenses:gifts --add-posting 'budget:gifts *-1' \ - --add-posting 'assets:budget *1' \ - > rewritten-tidy-output.journal - - It is important to understand that relative order of such entries in -journal is important. You can re-use result of previously added -postings. - - -File: hledger.info, Node: Diff output format, Next: rewrite vs print --auto, Prev: Re-write rules in a file, Up: rewrite - -31.2.2 Diff output format -------------------------- - -To use this tool for batch modification of your journal files you may -find useful output in form of unified diff. - -$ hledger rewrite --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' - - Output might look like: - ---- /tmp/examples/sample.journal -+++ /tmp/examples/sample.journal -@@ -18,3 +18,4 @@ - 2008/01/01 income -- assets:bank:checking $1 -+ assets:bank:checking $1 - income:salary -+ (liabilities:tax) 0 -@@ -22,3 +23,4 @@ - 2008/06/01 gift -- assets:bank:checking $1 -+ assets:bank:checking $1 - income:gifts -+ (liabilities:tax) 0 - - If you'll pass this through 'patch' tool you'll get transactions -containing the posting that matches your query be updated. Note that -multiple files might be update according to list of input files -specified via '--file' options and 'include' directives inside of these -files. - - Be careful. Whole transaction being re-formatted in a style of -output from 'hledger print'. - - See also: - - https://github.com/simonmichael/hledger/issues/99 - - -File: hledger.info, Node: rewrite vs print --auto, Prev: Diff output format, Up: rewrite - -31.2.3 rewrite vs. print -auto ------------------------------- - -This command predates print -auto, and currently does much the same -thing, but with these differences: - - * with multiple files, rewrite lets rules in any file affect all - other files. print -auto uses standard directive scoping; rules - affect only child files. - - * rewrite's query limits which transactions can be rewritten; all are - printed. print -auto's query limits which transactions are - printed. - - * rewrite applies rules specified on command line or in the journal. - print -auto applies rules specified in the journal. - - -File: hledger.info, Node: Maintenance commands, Next: PART 5 COMMON TASKS, Prev: Data generation commands, Up: Top - -32 Maintenance commands -*********************** - -* Menu: - -* check:: -* diff:: -* setup:: -* test:: - - -File: hledger.info, Node: check, Next: diff, Up: Maintenance commands - -32.1 check -========== - -Check for various kinds of errors in your data. - -Flags: -no command-specific flags - - hledger provides a number of built-in correctness checks to help -validate your data and prevent errors. Some are run automatically, some -when you enable '--strict' mode; or you can run any of them on demand by -providing them as arguments to the 'check' command. 'check' produces no -output and a zero exit code if all is well. Eg: - -hledger check # run basic checks -hledger check -s # run basic and strict checks -hledger check ordereddates payees # run basic checks and two others - - If you are an Emacs user, you can also configure flycheck-hledger to -run these checks, providing instant feedback as you edit the journal. - - Here are the checks currently available. Generally, they are -performed in the order they are shown here (and only the first failure -is reported). - -* Menu: - -* Basic checks:: -* Strict checks:: -* Other checks:: -* Custom checks:: - - -File: hledger.info, Node: Basic checks, Next: Strict checks, Up: check - -32.1.1 Basic checks -------------------- - -These important checks are performed by default, by almost all hledger -commands: - - * *parseable* - data files are in a supported format, with no syntax - errors and no invalid include directives. This ensures that all - files exist and are readable. - - * *autobalanced* - all transactions are balanced, after automatically - inferring missing amounts and conversion rates and then converting - amounts to cost. This ensures that each transaction's entry is - well formed. - - * *assertions* - all balance assertions in the journal are passing. - Balance assertions are a strong defense against errors; they help - catch many problems. If this check gets in your way, you can - disable it with '-I'/'--ignore-assertions'. Or you can add that to - your config file to disable it by default (and then use - '-s'/'--strict' or 'hledger check assertions' to enable it). - - -File: hledger.info, Node: Strict checks, Next: Other checks, Prev: Basic checks, Up: check - -32.1.2 Strict checks --------------------- - -These additional checks are performed by all commands when the -'-s'/'--strict' flag is used (strict mode). They provide extra -error-catching power to keep your data clean and correct. Strict mode -also always enables the 'assertions' check. - - * *balanced* - like 'autobalanced', but all conversions between - commodities must use explicit cost notation or equity postings. - This prevents wrong conversions caused by typos. - - * *commodities* - all commodity symbols used must be declared. This - guards against mistyping or omitting commodity symbols. Declaring - commodities also sets their precision for display and transaction - balancing. - - * *accounts* - all account names used must be declared. This - prevents the use of mis-spelled or outdated account names. - - -File: hledger.info, Node: Other checks, Next: Custom checks, Prev: Strict checks, Up: check - -32.1.3 Other checks -------------------- - -These are not wanted by everyone, but can be run using the 'check' -command: - - * *tags* - all tags used must be declared. This prevents mis-spelled - tag names. Note hledger fairly often finds unintended tags in - comments. - - * *payees* - all payees used in transactions must be declared. This - will force you to declare any new payee name before using it. Most - people will probably find this a bit too strict. - - * *ordereddates* - within each file, transactions must be ordered by - date. This is a simple and effective error catcher. It's not - included in strict mode, but you can add it by running 'hledger - check -s ordereddates'. If enabled, this check is performed before - balance assertions. - - * *recentassertions* - all accounts with balance assertions must have - one that's within the 7 days before their latest posting. This - will encourage adding balance assertions for your active - asset/liability accounts, which in turn should encourage you to - reconcile regularly with those real world balances - another strong - defense against errors. 'hledger close --assert' can help generate - assertion entries. Over time the older assertions become somewhat - redundant, and you can remove them if you like (they don't affect - performance much, but they add some noise to the journal). - - * *uniqueleafnames* - no two accounts may have the same last account - name part (eg the 'checking' in 'assets:bank:checking'). This - ensures each account can be matched by a unique short name, easier - to remember and to type. - - -File: hledger.info, Node: Custom checks, Prev: Other checks, Up: check - -32.1.4 Custom checks --------------------- - -You can build your own custom checks with add-on command scripts. See -also Cookbook > Scripting. Here are some examples from hledger/bin/: - - * *hledger-check-tagfiles* - all tag values containing / (a forward - slash) exist as file paths - - * *hledger-check-fancyassertions* - more complex balance assertions - are passing - - -File: hledger.info, Node: diff, Next: setup, Prev: check, Up: Maintenance commands - -32.2 diff -========= - -Compares a particular account's transactions in two input files. It -shows any transactions to this account which are in one file but not in -the other. - -Flags: -no command-specific flags - - More precisely: for each posting affecting this account in either -file, this command looks for a corresponding posting in the other file -which posts the same amount to the same account (ignoring date, -description, etc). - - Since it compares postings, not transactions, this also works when -multiple bank transactions have been combined into a single journal -entry. - - This command is useful eg if you have downloaded an account's -transactions from your bank (eg as CSV data): when hledger and your bank -disagree about the account balance, you can compare the bank data with -your journal to find out the cause. - - Examples: - -$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro -These transactions are in the first file only: - -2014/01/01 Opening Balances - assets:bank:giro EUR ... - ... - equity:opening balances EUR -... - -These transactions are in the second file only: - - -File: hledger.info, Node: setup, Next: test, Prev: diff, Up: Maintenance commands - -32.3 setup -========== - -Check the status of the hledger installation. - -Flags: -no command-specific flags - - 'setup' tests your hledger installation and prints a list of results, -sometimes with helpful hints. This is a good first command to run after -installing hledger. Also after upgrading, or when something's not -working, or just when you want a reminder of where things are. - - It makes one network request to detect the latest hledger release -version. It's ok if this fails or times out. It will use ANSI color by -default, unless disabled by NO_COLOR or -color=n. It does not use a -pager or a config file. - - It expects that the hledger version you are running is installed in -your PATH. If not, it will stop until you have done that (to keep things -simple). - - Example: - -$ hledger setup -Checking your hledger setup.. -Legend: good, neutral, unknown, warning - -hledger -* is a released version ? no hledger 1.42.99-gbca4b39c5-20250425, mac-aarch64 -* is up to date ? yes 1.42.99 installed, latest is 1.42.1 -* is a native binary for this machine ? yes aarch64 -* is installed in PATH ? yes /Users/simon/.local/bin/hledger -* has a system text encoding configured ? yes UTF-8, data files should use this encoding -* has a user config file ? (optional) no -* current directory has a local config ? yes /Users/simon/src/hledger/hledger.conf -* the config file is readable ? yes /Users/simon/src/hledger/hledger.conf - -terminal -* the NO_COLOR variable is defined ? no -* --color is configured by config file ? no -* hledger will use color by default ? yes -* the PAGER variable is defined ? yes less -* --pager is configured by config file ? no -* hledger will use a pager when needed ? yes /opt/homebrew/bin/less -* the LESS variable is defined ? yes -* the HLEDGER_LESS variable is defined ? no -* adjusting LESS variable for color etc. ? yes -* --pretty is enabled by config file ? no tables will use ASCII characters -* bash shell completions are installed ? ? -* zsh shell completions are installed ? ? - -journal -* the LEDGER_FILE variable is defined ? yes /Users/simon/finance/2025/2025.journal -* a default journal file is readable ? yes /Users/simon/finance/2025/2025.journal -* it includes additional files ? yes 15 -* all commodities are declared ? yes 10 -* all accounts are declared ? yes 160 -* all accounts have types ? no 14 untyped -* accounts of each type were detected ? yes ALERXCV -* commodities/accounts are checked ? no use -s to check commodities/accounts -* balance assertions are checked ? yes use -I to ignore assertions - - -File: hledger.info, Node: test, Prev: setup, Up: Maintenance commands - -32.4 test -========= - -Run built-in unit tests. - -Flags: -no command-specific flags - - This command runs the unit tests built in to hledger and hledger-lib, -printing the results on stdout. If any test fails, the exit code will -be non-zero. - - This is mainly used by hledger developers, but you can also use it to -sanity-check the installed hledger executable on your platform. All -tests are expected to pass - if you ever see a failure, please report as -a bug! - - Any arguments before a '--' argument will be passed to the 'tasty' -test runner as test-selecting -p patterns, and any arguments after '--' -will be passed to tasty unchanged. - - Examples: - -$ hledger test # run all unit tests -$ hledger test balance # run tests with "balance" in their name -$ hledger test -- -h # show tasty's options - - -File: hledger.info, Node: PART 5 COMMON TASKS, Next: Getting help, Prev: Maintenance commands, Up: Top - -33 PART 5: COMMON TASKS -*********************** - -Here are some quick examples of how to do some basic tasks with hledger. - - -File: hledger.info, Node: Getting help, Next: Constructing command lines, Prev: PART 5 COMMON TASKS, Up: Top - -34 Getting help -*************** - -Here's how to list commands and view options and command docs: - -$ hledger # show available commands -$ hledger --help # show common options -$ hledger CMD --help # show CMD's options, common options and CMD's documentation - - You can also view your hledger version's manual in several formats by -using the help command. Eg: - -$ hledger help # show the hledger manual with info, man or $PAGER (best available) -$ hledger help journal # show the journal topic in the hledger manual -$ hledger help --help # find out more about the help command - - To view manuals and introductory docs on the web, visit -https://hledger.org. Chat and mail list support and discussion archives -can be found at https://hledger.org/support. - - -File: hledger.info, Node: Constructing command lines, Next: Starting a journal file, Prev: Getting help, Up: Top - -35 Constructing command lines -***************************** - -hledger has a flexible command line interface. We strive to keep it -simple and ergonomic, but if you run into one of the sharp edges -described in OPTIONS, here are some tips that might help: - - * command-specific options must go after the command (it's fine to - put common options there too: 'hledger CMD OPTS ARGS') - * you can run addon commands via hledger ('hledger ui [ARGS]') or - directly ('hledger-ui [ARGS]') - * enclose "problematic" arguments in single quotes - * if needed, also add a backslash to hide regular expression - metacharacters from the shell - * to see how a misbehaving command line is being parsed, add - '--debug=2'. - - -File: hledger.info, Node: Starting a journal file, Next: Setting LEDGER_FILE, Prev: Constructing command lines, Up: Top - -36 Starting a journal file -************************** - -hledger looks for your accounting data in a journal file, -'$HOME/.hledger.journal' by default: - -$ hledger stats -The hledger journal file "/Users/simon/.hledger.journal" was not found. -Please create it first, eg with "hledger add" or a text editor. -Or, specify an existing journal file with -f or LEDGER_FILE. - - You can override this by setting the 'LEDGER_FILE' environment -variable (see below). It's a good practice to keep this important file -under version control, and to start a new file each year. So you could -do something like this: - -$ mkdir ~/finance -$ cd ~/finance -$ git init -Initialized empty Git repository in /Users/simon/finance/.git/ -$ touch 2023.journal -$ echo "export LEDGER_FILE=$HOME/finance/2023.journal" >> ~/.profile -$ source ~/.profile -$ hledger stats -Main file : /Users/simon/finance/2023.journal -Included files : -Transactions span : to (0 days) -Last transaction : none -Transactions : 0 (0.0 per day) -Transactions last 30 days: 0 (0.0 per day) -Transactions last 7 days : 0 (0.0 per day) -Payees/descriptions : 0 -Accounts : 0 (depth 0) -Commodities : 0 () -Market prices : 0 () - - -File: hledger.info, Node: Setting LEDGER_FILE, Next: Setting opening balances, Prev: Starting a journal file, Up: Top - -37 Setting LEDGER_FILE -********************** - -How to set 'LEDGER_FILE' permanently depends on your setup: - - On unix and mac, running these commands in the terminal will work for -many people; adapt as needed: - -$ echo 'export LEDGER_FILE=~/finance/2023.journal' >> ~/.profile -$ source ~/.profile - - When correctly configured, in a new terminal window 'env | grep -LEDGER_FILE' will show your file, and so will 'hledger files'. - - On mac, this additional step might be helpful for GUI applications -(like Emacs started from the dock): add an entry to -'~/.MacOSX/environment.plist' like - -{ - "LEDGER_FILE" : "~/finance/2023.journal" -} - - and then run 'killall Dock' in a terminal window (or restart the -machine). - - On Windows, see https://www.java.com/en/download/help/path.html, or -try running these commands in a powershell window (let us know if it -persists across a reboot, and if you need to be an Administrator): - -> CD -> MKDIR finance -> SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal" - - When correctly configured, in a new terminal window -'$env:LEDGER_FILE' will show the file path, and so will 'hledger files'. - - -File: hledger.info, Node: Setting opening balances, Next: Recording transactions, Prev: Setting LEDGER_FILE, Up: Top - -38 Setting opening balances -*************************** - -Pick a starting date for which you can look up the balances of some -real-world assets (bank accounts, wallet..) and liabilities (credit -cards..). - - To avoid a lot of data entry, you may want to start with just one or -two accounts, like your checking account or cash wallet; and pick a -recent starting date, like today or the start of the week. You can -always come back later and add more accounts and older transactions, eg -going back to january 1st. - - Add an opening balances transaction to the journal, declaring the -balances on this date. Here are two ways to do it: - - * The first way: open the journal in any text editor and save an - entry like this: - - 2023-01-01 * opening balances - assets:bank:checking $1000 = $1000 - assets:bank:savings $2000 = $2000 - assets:cash $100 = $100 - liabilities:creditcard $-50 = $-50 - equity:opening/closing balances - - These are start-of-day balances, ie whatever was in the account at - the end of the previous day. - - The * after the date is an optional status flag. Here it means - "cleared & confirmed". - - The currency symbols are optional, but usually a good idea as - you'll be dealing with multiple currencies sooner or later. - - The = amounts are optional balance assertions, providing extra - error checking. - - * The second way: run 'hledger add' and follow the prompts to record - a similar transaction: - - $ hledger add - Adding transactions to journal file /Users/simon/finance/2023.journal - Any command line arguments will be used as defaults. - Use tab key to complete, readline keys to edit, enter to accept defaults. - An optional (CODE) may follow transaction dates. - An optional ; COMMENT may follow descriptions or amounts. - If you make a mistake, enter < at any prompt to go one step backward. - To end a transaction, enter . when prompted. - To quit, enter . at a date prompt or press control-d or control-c. - Date [2023-02-07]: 2023-01-01 - Description: * opening balances - Account 1: assets:bank:checking - Amount 1: $1000 - Account 2: assets:bank:savings - Amount 2 [$-1000]: $2000 - Account 3: assets:cash - Amount 3 [$-3000]: $100 - Account 4: liabilities:creditcard - Amount 4 [$-3100]: $-50 - Account 5: equity:opening/closing balances - Amount 5 [$-3050]: - Account 6 (or . or enter to finish this transaction): . - 2023-01-01 * opening balances - assets:bank:checking $1000 - assets:bank:savings $2000 - assets:cash $100 - liabilities:creditcard $-50 - equity:opening/closing balances $-3050 - - Save this transaction to the journal ? [y]: - Saved. - Starting the next transaction (. or ctrl-D/ctrl-C to quit) - Date [2023-01-01]: . - - If you're using version control, this could be a good time to commit -the journal. Eg: - -$ git commit -m 'initial balances' 2023.journal - - -File: hledger.info, Node: Recording transactions, Next: Reconciling, Prev: Setting opening balances, Up: Top - -39 Recording transactions -************************* - -As you spend or receive money, you can record these transactions using -one of the methods above (text editor, hledger add) or by using the -hledger-iadd or hledger-web add-ons, or by using the import command to -convert CSV data downloaded from your bank. - - Here are some simple transactions, see the hledger_journal(5) manual -and hledger.org for more ideas: - -2023/1/10 * gift received - assets:cash $20 - income:gifts - -2023.1.12 * farmers market - expenses:food $13 - assets:cash - -2023-01-15 paycheck - income:salary - assets:bank:checking $1000 - - -File: hledger.info, Node: Reconciling, Next: Reporting, Prev: Recording transactions, Up: Top - -40 Reconciling -************** - -Periodically you should reconcile - compare your hledger-reported -balances against external sources of truth, like bank statements or your -bank's website - to be sure that your ledger accurately represents the -real-world balances (and, that the real-world institutions have not made -a mistake!). This gets easy and fast with (1) practice and (2) -frequency. If you do it daily, it can take 2-10 minutes. If you let it -pile up, expect it to take longer as you hunt down errors and -discrepancies. - - A typical workflow: - - 1. Reconcile cash. Count what's in your wallet. Compare with what - hledger reports ('hledger bal cash'). If they are different, try - to remember the missing transaction, or look for the error in the - already-recorded transactions. A register report can be helpful - ('hledger reg cash'). If you can't find the error, add an - adjustment transaction. Eg if you have $105 after the above, and - can't explain the missing $2, it could be: - - 2023-01-16 * adjust cash - assets:cash $-2 = $105 - expenses:misc - - 2. Reconcile checking. Log in to your bank's website. Compare - today's (cleared) balance with hledger's cleared balance ('hledger - bal checking -C'). If they are different, track down the error or - record the missing transaction(s) or add an adjustment transaction, - similar to the above. Unlike the cash case, you can usually - compare the transaction history and running balance from your bank - with the one reported by 'hledger reg checking -C'. This will be - easier if you generally record transaction dates quite similar to - your bank's clearing dates. - - 3. Repeat for other asset/liability accounts. - - Tip: instead of the register command, use hledger-ui to see a -live-updating register while you edit the journal: 'hledger-ui --watch ---register checking -C' - - After reconciling, it could be a good time to mark the reconciled -transactions' status as "cleared and confirmed", if you want to track -that, by adding the '*' marker. Eg in the paycheck transaction above, -insert '*' between '2023-01-15' and 'paycheck' - - If you're using version control, this can be another good time to -commit: - -$ git commit -m 'txns' 2023.journal - - -File: hledger.info, Node: Reporting, Next: Migrating to a new file, Prev: Reconciling, Up: Top - -41 Reporting -************ - -Here are some basic reports. - - Show all transactions: - -$ hledger print -2023-01-01 * opening balances - assets:bank:checking $1000 - assets:bank:savings $2000 - assets:cash $100 - liabilities:creditcard $-50 - equity:opening/closing balances $-3050 - -2023-01-10 * gift received - assets:cash $20 - income:gifts - -2023-01-12 * farmers market - expenses:food $13 - assets:cash - -2023-01-15 * paycheck - income:salary - assets:bank:checking $1000 - -2023-01-16 * adjust cash - assets:cash $-2 = $105 - expenses:misc - - Show account names, and their hierarchy: - -$ hledger accounts --tree -assets - bank - checking - savings - cash -equity - opening/closing balances -expenses - food - misc -income - gifts - salary -liabilities - creditcard - - Show all account totals: - -$ hledger balance - $4105 assets - $4000 bank - $2000 checking - $2000 savings - $105 cash - $-3050 equity:opening/closing balances - $15 expenses - $13 food - $2 misc - $-1020 income - $-20 gifts - $-1000 salary - $-50 liabilities:creditcard --------------------- - 0 - - Show only asset and liability balances, as a flat list, limited to -depth 2: - -$ hledger bal assets liabilities -2 - $4000 assets:bank - $105 assets:cash - $-50 liabilities:creditcard --------------------- - $4055 - - Show the same thing without negative numbers, formatted as a simple -balance sheet: - -$ hledger bs -2 -Balance Sheet 2023-01-16 - - || 2023-01-16 -========================++============ - Assets || -------------------------++------------ - assets:bank || $4000 - assets:cash || $105 -------------------------++------------ - || $4105 -========================++============ - Liabilities || -------------------------++------------ - liabilities:creditcard || $50 -------------------------++------------ - || $50 -========================++============ - Net: || $4055 - - The final total is your "net worth" on the end date. (Or use 'bse' -for a full balance sheet with equity.) - - Show income and expense totals, formatted as an income statement: - -hledger is -Income Statement 2023-01-01-2023-01-16 - - || 2023-01-01-2023-01-16 -===============++======================= - Revenues || ----------------++----------------------- - income:gifts || $20 - income:salary || $1000 ----------------++----------------------- - || $1020 -===============++======================= - Expenses || ----------------++----------------------- - expenses:food || $13 - expenses:misc || $2 ----------------++----------------------- - || $15 -===============++======================= - Net: || $1005 - - The final total is your net income during this period. - - Show transactions affecting your wallet, with running total: - -$ hledger register cash -2023-01-01 opening balances assets:cash $100 $100 -2023-01-10 gift received assets:cash $20 $120 -2023-01-12 farmers market assets:cash $-13 $107 -2023-01-16 adjust cash assets:cash $-2 $105 - - Show weekly posting counts as a bar chart: - -$ hledger activity -W -2019-12-30 ***** -2023-01-06 **** -2023-01-13 **** - - -File: hledger.info, Node: Migrating to a new file, Next: BUGS, Prev: Reporting, Up: Top - -42 Migrating to a new file -************************** - -At the end of the year, you may want to continue your journal in a new -file, so that old transactions don't slow down or clutter your reports, -and to help ensure the integrity of your accounting history. See the -close command. - - If using version control, don't forget to 'git add' the new file. - - -File: hledger.info, Node: BUGS, Prev: Migrating to a new file, Up: Top - -43 BUGS -******* - -We welcome bug reports in the hledger issue tracker -(https://bugs.hledger.org), or on the hledger chat or mail list -(https://hledger.org/support). - - Some known issues and limitations: - - hledger uses the system's text encoding when reading non-ascii text. -If no system encoding is configured, or if the data's encoding is -different, hledger will give an error. (See Text encoding, -Troubleshooting.) - - On Microsoft Windows, depending what kind of terminal window you use, -non-ascii characters, ANSI text formatting, and/or the add command's TAB -key, may not be fully supported. (For best results, try a powershell -window.) - - When processing large data files, hledger uses more memory than -Ledger. - -* Menu: - -* Troubleshooting:: - - -File: hledger.info, Node: Troubleshooting, Up: BUGS - -43.1 Troubleshooting -==================== - -Here are some common issues you might encounter when you run hledger, -and how to resolve them (and remember also you can usually get quick -Support): - - *PATH issues: I get an error like "No command 'hledger' found"* -Depending how you installed hledger, the executables may not be in your -shell's PATH. Eg on unix systems, stack installs hledger in -'~/.local/bin' and cabal installs it in '~/.cabal/bin'. You may need to -add one of these directories to your shell's PATH, and/or open a new -terminal window. - - *LEDGER_FILE issues: I configured LEDGER_FILE but hledger is not -using it* - - * 'LEDGER_FILE' should be a real environment variable, not just a - shell variable. Eg on unix, the command 'env | grep LEDGER_FILE' - should show it. You may need to use 'export' (see - https://stackoverflow.com/a/7411509). On Windows, - '$env:LEDGER_FILE' should show it. - * You may need to force your shell to see the new configuration. A - simple way is to close your terminal window and open a new one. - - *Text decoding issues: I get errors like "Illegal byte sequence" or -"Invalid or incomplete multibyte or wide character" or -"commitAndReleaseBuffer: invalid argument (invalid character)"* -hledger usually needs its input to be decodable with the system locale's -text encoding. See Text encoding and Install: Text encoding. - - *COMPATIBILITY ISSUES: hledger gives an error with my Ledger file* -Not all of Ledger's journal file syntax or feature set is supported. -See hledger and Ledger for full details. - - -Tag Table: -Node: Top208 -Node: PART 1 USER INTERFACE4306 -Node: Input4445 -Node: Text encoding5537 -Node: Data formats6286 -Node: Standard input8020 -Node: Multiple files8409 -Node: Strict mode9146 -Node: Commands9980 -Node: Add-on commands11262 -Node: Options12313 -Node: Special characters19463 -Node: Escaping shell special characters20413 -Node: Escaping on Windows21657 -Node: Escaping regular expression special characters22390 -Node: Escaping add-on arguments23377 -Node: Escaping in other situations24406 -Node: Using a wild card25365 -Node: Unicode characters25744 -Node: Regular expressions27165 -Node: hledger's regular expressions30424 -Node: Argument files32065 -Node: Config files32768 -Node: Shell completions36037 -Node: Output36526 -Node: Output destination36717 -Node: Output format37275 -Node: Text output39061 -Node: Box-drawing characters40040 -Node: Colour40540 -Node: Paging41126 -Node: HTML output42645 -Node: CSV / TSV output43063 -Node: FODS output43317 -Node: Beancount output44121 -Node: Beancount account names45622 -Node: Beancount commodity names46163 -Node: Beancount virtual postings46810 -Node: Beancount metadata47126 -Node: Beancount costs47906 -Node: Beancount operating currency48322 -Node: SQL output48772 -Node: JSON output49563 -Node: Commodity styles50380 -Node: Debug output51267 -Node: Environment52099 -Node: PART 2 DATA FORMATS52756 -Node: Journal52899 -Node: Journal cheatsheet55377 -Node: Comments61628 -Node: Transactions62572 -Node: Dates63709 -Node: Simple dates63861 -Node: Posting dates64477 -Node: Status65564 -Node: Code67330 -Node: Description67665 -Node: Payee and note68352 -Node: Transaction comments69443 -Node: Postings69959 -Node: Debits and credits71122 -Node: The two space delimiter71732 -Node: Account names72297 -Node: Amounts74101 -Node: Decimal marks75130 -Node: Digit group marks76234 -Node: Commodity76869 -Node: Costs77986 -Node: Balance assertions80238 -Node: Assertions and ordering81486 -Node: Assertions and multiple files82205 -Node: Assertions and costs83373 -Node: Assertions and commodities84020 -Node: Assertions and subaccounts85679 -Node: Assertions and status86339 -Node: Assertions and virtual postings86759 -Node: Assertions and auto postings87124 -Node: Assertions and precision87999 -Node: Assertions and hledger add88483 -Node: Posting comments89231 -Node: Transaction balancing89771 -Node: Tags91979 -Node: Querying with tags93273 -Node: Displaying tags94072 -Node: When to use tags ?94468 -Node: Tag names95132 -Node: Special tags95685 -Node: Directives97250 -Node: Directives and multiple files98707 -Node: Directive effects99652 -Node: account directive102808 -Node: Account comments104258 -Node: Account error checking104917 -Node: Account display order106454 -Node: Account types107652 -Node: alias directive110927 -Node: Basic aliases112138 -Node: Regex aliases113013 -Node: Combining aliases114060 -Node: Aliases and multiple files115514 -Node: end aliases directive116297 -Node: Aliases can generate bad account names116665 -Node: Aliases and account types117498 -Node: commodity directive118390 -Node: Commodity directive syntax119977 -Node: Commodity error checking121626 -Node: decimal-mark directive122101 -Node: include directive122680 -Node: P directive124898 -Node: payee directive125932 -Node: tag directive126554 -Node: Periodic transactions127166 -Node: Periodic rule syntax129320 -Node: Periodic rules and relative dates130143 -Node: Two spaces between period expression and description!130920 -Node: Auto postings131881 -Node: Auto postings and multiple files135167 -Node: Auto postings and dates135572 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions136013 -Node: Auto posting tags136859 -Node: Auto postings on forecast transactions only137754 -Node: Other syntax138224 -Node: Balance assignments138996 -Node: Balance assignments and costs140524 -Node: Balance assignments and multiple files140946 -Node: Bracketed posting dates141369 -Node: D directive142067 -Node: apply account directive143840 -Node: Y directive144707 -Node: Secondary dates145695 -Node: Star comments147180 -Node: Valuation expressions147872 -Node: Virtual postings148171 -Node: Other Ledger directives149795 -Node: Other cost/lot notations150557 -Node: CSV153398 -Node: CSV rules cheatsheet155564 -Node: source157663 -Node: Data cleaning / generating commands159062 -Node: archive160924 -Node: encoding161852 -Node: separator162895 -Node: skip163548 -Node: date-format164198 -Node: timezone165143 -Node: newest-first166269 -Node: intra-day-reversed166982 -Node: decimal-mark167584 -Node: fields list168064 -Node: Field assignment169872 -Node: Field names171091 -Node: date field172423 -Node: date2 field172587 -Node: status field172782 -Node: code field172972 -Node: description field173160 -Node: comment field173377 -Node: account field173934 -Node: amount field174652 -Node: currency field177491 -Node: balance field177899 -Node: if block178422 -Node: Matchers179949 -Node: Multiple matchers181939 -Node: Match groups182747 -Node: if table183640 -Node: balance-type185703 -Node: include186530 -Node: Working with CSV187099 -Node: Rapid feedback187651 -Node: Valid CSV188234 -Node: File Extension189110 -Node: Reading CSV from standard input189845 -Node: Reading multiple CSV files190231 -Node: Reading files specified by rule190707 -Node: Valid transactions192104 -Node: Deduplicating importing192929 -Node: Setting amounts194158 -Node: Amount signs196685 -Node: Setting currency/commodity197750 -Node: Amount decimal places199126 -Node: Referencing other fields200383 -Node: How CSV rules are evaluated201491 -Node: Well factored rules204208 -Node: CSV rules examples204698 -Node: Bank of Ireland204896 -Node: Coinbase206493 -Node: Amazon207676 -Node: Paypal209518 -Node: Timeclock217268 -Node: Timedot221321 -Node: Timedot examples224798 -Node: PART 3 REPORTING CONCEPTS227075 -Node: Time periods227239 -Node: Report start & end date227512 -Node: Smart dates228988 -Node: Report intervals231111 -Node: Date adjustments231685 -Node: Start date adjustment231905 -Node: End date adjustment232808 -Node: Period headings233589 -Node: Period expressions234522 -Node: Period expressions with a report interval236427 -Node: More complex report intervals236875 -Node: Multiple weekday intervals238991 -Node: Depth240002 -Node: Queries241582 -Node: Query types244254 -Node: acct query244629 -Node: amt query244940 -Node: code query245637 -Node: cur query245832 -Node: desc query246438 -Node: date query246621 -Node: date2 query247017 -Node: depth query247308 -Node: note query247644 -Node: payee query247910 -Node: real query248191 -Node: status query248396 -Node: type query248636 -Node: tag query249169 -Node: Negative queries249798 -Node: not query249980 -Node: Space-separated queries250267 -Node: Boolean queries250955 -Node: expr query252273 -Node: any query252953 -Node: all query253406 -Node: Queries and command options253988 -Node: Queries and account aliases254436 -Node: Queries and valuation254761 -Node: Pivoting255123 -Node: Generating data257399 -Node: Forecasting259199 -Node: --forecast259855 -Node: Inspecting forecast transactions260956 -Node: Forecast reports262289 -Node: Forecast tags263398 -Node: Forecast period in detail264018 -Node: Forecast troubleshooting265106 -Node: Budgeting266177 -Node: Amount formatting266737 -Node: Commodity display style266981 -Node: Rounding268822 -Node: Trailing decimal marks269427 -Node: Amount parseability270360 -Node: Cost reporting271969 -Node: Recording costs272800 -Node: Reporting at cost274527 -Node: Equity conversion postings275292 -Node: Inferring equity conversion postings277937 -Node: Combining costs and equity conversion postings279079 -Node: Requirements for detecting equity conversion postings280304 -Node: Infer cost and equity by default ?281826 -Node: Value reporting282263 -Node: -V Value283199 -Node: -X Value in specified commodity283526 -Node: Valuation date283876 -Node: Finding market price284709 -Node: --infer-market-prices market prices from transactions286089 -Node: Valuation commodity289133 -Node: --value Flexible valuation290566 -Node: Valuation examples292409 -Node: Interaction of valuation and queries294553 -Node: Effect of valuation on reports295270 -Node: PART 4 COMMANDS303120 -Node: Help commands305909 -Node: commands306095 -Node: demo306303 -Node: help307396 -Node: User interface commands309101 -Node: repl309312 -Node: Examples311576 -Node: run312134 -Node: Examples 2314549 -Node: ui315573 -Node: web315710 -Node: Data entry commands315838 -Node: add316099 -Node: add and balance assertions318673 -Node: add and balance assignments319397 -Node: import319958 -Node: Import dry run321037 -Node: Overlap detection321985 -Node: First import324871 -Node: Importing balance assignments326066 -Node: Import and commodity styles327121 -Node: Import archiving327555 -Node: Import special cases328380 -Node: Deduplication328598 -Node: Varying file name329089 -Node: Multiple versions329473 -Node: Basic report commands330580 -Node: accounts330881 -Node: codes333527 -Node: commodities334549 -Node: descriptions335306 -Node: files335766 -Node: notes336063 -Node: payees336575 -Node: prices337487 -Node: stats338379 -Node: tags340120 -Node: Standard report commands341657 -Node: print341962 -Node: print explicitness344666 -Node: print amount style345586 -Node: print parseability346824 -Node: print other features347743 -Node: print output format348704 -Node: aregister351989 -Node: aregister and posting dates356553 -Node: register357454 -Node: Custom register output364694 -Node: balancesheet365879 -Node: balancesheetequity370844 -Node: cashflow376179 -Node: incomestatement380992 -Node: Advanced report commands385841 -Node: balance386049 -Node: balance features391470 -Node: Simple balance report393573 -Node: Balance report line format395383 -Node: Filtered balance report397743 -Node: List or tree mode398262 -Node: Depth limiting399775 -Node: Dropping top-level accounts400542 -Node: Showing declared accounts401052 -Node: Sorting by amount401782 -Node: Percentages402636 -Node: Multi-period balance report403343 -Node: Balance change end balance406095 -Node: Balance report modes407732 -Node: Calculation mode408411 -Node: Accumulation mode409115 -Node: Valuation mode410216 -Node: Combining balance report modes411560 -Node: Budget report413590 -Node: Using the budget report415890 -Node: Budget date surprises418166 -Node: Selecting budget goals419530 -Node: Budgeting vs forecasting420478 -Node: Balance report layout422155 -Node: Wide layout423360 -Node: Tall layout425765 -Node: Bare layout427071 -Node: Tidy layout429135 -Node: Balance report output430679 -Node: Some useful balance reports431453 -Node: roi432713 -Node: Spaces and special characters in --inv and --pnl434960 -Node: Semantics of --inv and --pnl435686 -Node: IRR and TWR explained437773 -Node: Chart commands441184 -Node: activity441365 -Node: Data generation commands441862 -Node: close442068 -Node: close --clopen444631 -Node: close --close446805 -Node: close --open447329 -Node: close --assert447579 -Node: close --assign447906 -Node: close --retain448585 -Node: close customisation449442 -Node: close and balance assertions451086 -Node: close examples452608 -Node: Retain earnings452845 -Node: Migrate balances to a new file453348 -Node: More detailed close examples454710 -Node: rewrite454932 -Node: Re-write rules in a file457492 -Node: Diff output format458793 -Node: rewrite vs print --auto460063 -Node: Maintenance commands460777 -Node: check460996 -Node: Basic checks462078 -Node: Strict checks463099 -Node: Other checks464036 -Node: Custom checks465788 -Node: diff466243 -Node: setup467451 -Node: test470318 -Node: PART 5 COMMON TASKS471221 -Node: Getting help471454 -Node: Constructing command lines472363 -Node: Starting a journal file473208 -Node: Setting LEDGER_FILE474592 -Node: Setting opening balances475850 -Node: Recording transactions479172 -Node: Reconciling479897 -Node: Reporting482286 -Node: Migrating to a new file486400 -Node: BUGS486849 -Node: Troubleshooting487679 + This manual is for hledger's command line interface, version 1.50.3. +It also describes the common options, file formats and concepts used by +all hledger programs. It might accidentally teach you some +bookkeeping/accounting as well! You don't need to know everything in +here to use hledger productively, but when you have a question about +functionality, this doc should answer it. It is detailed, so do skip +ahead or skim when needed. You can read it on hledger.org, or as an +info manual or man page on your system. You can also open a built-in +copy, at a point of interest, by running +'hledger --man [CMD]', 'hledger --info [CMD]' or 'hledger help [TOPIC]'. + + (And for shorter help, try 'hledger --tldr [CMD]'.) + + The main function of the hledger CLI is to read plain text files +describing financial transactions, crunch the numbers, and print a +useful report on the terminal (or save it as HTML, CSV, JSON or SQL). +Many reports are available, as subcommands. hledger will also detect +other 'hledger-*' executables as extra subcommands. + + hledger usually reads from (and appends to) a journal file specified +by the 'LEDGER_FILE' environment variable (defaulting to +'$HOME/.hledger.journal'); or you can specify files with '-f' options. +It can also read timeclock files, timedot files, or any CSV/SSV/TSV file +with a date field. + + Here is a small journal file describing one transaction: + +2015-10-16 bought food + expenses:food $10 + assets:cash + + Transactions are dated movements of money (etc.) between two or more +_accounts_: bank accounts, your wallet, revenue/expense categories, +people, etc. You can choose any account names you wish, using ':' to +indicate subaccounts. There must be at least two spaces between account +name and amount. Positive amounts are inflow to that account (_debit_), +negatives are outflow from it (_credit_). (Some reports show revenue, +liability and equity account balances as negative numbers as a result; +this is normal.) + + hledger's add command can help you add transactions, or you can +install other data entry UIs like hledger-web or hledger-iadd. For more +extensive/efficient changes, use a text editor: Emacs + ledger-mode, VIM ++ vim-ledger, or VS Code + hledger-vscode are some good choices (see +https://hledger.org/editors.html). + + To get started, run 'hledger add' and follow the prompts, or save +some entries like the above in '$HOME/.hledger.journal', then try +commands like: + +$ hledger print -x +$ hledger aregister assets +$ hledger balance +$ hledger balancesheet +$ hledger incomestatement + + Run 'hledger' to list the commands. See also the "Starting a journal +file" and "Setting opening balances" sections in PART 5: COMMON TASKS. + +* Menu: + +* PART 1 USER INTERFACE:: +* Input:: +* Commands:: +* Options:: +* Output:: +* Environment:: +* PART 2 DATA FORMATS:: +* Journal:: +* CSV:: +* Timeclock:: +* Timedot:: +* PART 3 REPORTING CONCEPTS:: +* Time periods:: +* Depth:: +* Queries:: +* Pivoting:: +* Generating data:: +* Forecasting:: +* Budgeting:: +* Amount formatting:: +* Cost reporting:: +* Value reporting:: +* PART 4 COMMANDS:: +* Help commands:: +* User interface commands:: +* Data entry commands:: +* Basic report commands:: +* Standard report commands:: +* Advanced report commands:: +* Chart commands:: +* Data generation commands:: +* Maintenance commands:: +* PART 5 COMMON TASKS:: +* Getting help:: +* Constructing command lines:: +* Starting a journal file:: +* Setting LEDGER_FILE:: +* Setting opening balances:: +* Recording transactions:: +* Reconciling:: +* Reporting:: +* Migrating to a new file:: +* BUGS:: + + +File: hledger.info, Node: PART 1 USER INTERFACE, Next: Input, Prev: Top, Up: Top + +1 PART 1: USER INTERFACE +************************ + + +File: hledger.info, Node: Input, Next: Commands, Prev: PART 1 USER INTERFACE, Up: Top + +2 Input +******* + +hledger reads one or more data files, each time you run it. You can +specify a file with '-f', like so + +$ hledger -f FILE [-f FILE2 ...] print + + Files are most often in hledger's journal format, with the '.journal' +file extension ('.hledger' or '.j' also work); these files describe +transactions, like an accounting general journal. + + When no file is specified, hledger looks for '.hledger.journal' in +your home directory. + + But most people prefer to keep financial files in a dedicated folder, +perhaps with version control. Also, starting a new journal file each +year is common (it's not required, but helps keep things fast and +organised). So we usually configure a different journal file, by +setting the 'LEDGER_FILE' environment variable, to something like +'~/finance/2023.journal'. For more about how to do that on your system, +see Common tasks > Setting LEDGER_FILE. + +* Menu: + +* Text encoding:: +* Data formats:: +* Standard input:: +* Multiple files:: +* Strict mode:: + + +File: hledger.info, Node: Text encoding, Next: Data formats, Up: Input + +2.1 Text encoding +================= + +hledger expects non-ascii input to be decodable with the system locale's +text encoding. (For CSV/SSV/TSV files, this can be overridden by the +'encoding' CSV rule.) + + So, trying to read non-ascii files which have the wrong text +encoding, or when no system locale is configured, will fail. To fix +this, configure your system locale appropriately, and/or convert the +files to your system's text encoding (using 'iconv' on unix, or +powershell or notepad on Windows). See Install: Text encoding for more +tips. + + hledger's output will use the system locale's encoding. + + hledger's docs and example files mostly use UTF-8 encoding. + + +File: hledger.info, Node: Data formats, Next: Standard input, Prev: Text encoding, Up: Input + +2.2 Data formats +================ + +Usually the data file is in hledger's journal format, but it can be in +any of the supported file formats, which currently are: + +Reader: Reads: Automatically used for + files with extensions: +--------------------------------------------------------------------------- +'journal' hledger journal files and some '.journal' '.j' + Ledger journals, for '.hledger' '.ledger' + transactions +'timeclock' timeclock files, for precise '.timeclock' + time logging +'timedot' timedot files, for approximate '.timedot' + time logging +'csv' Comma- or other '.csv' + delimiter-separated values, for + data import +'ssv' Semicolon separated values '.ssv' +'tsv' Tab separated values '.tsv' +'rules' CSV/SSV/TSV/other separated '.rules' + values, alternate way + + These formats are described in more detail below. + + hledger detects the format automatically based on the file extensions +shown above. If it can't recognise the file extension, it assumes +'journal' format. So for non-journal files, it's important to use a +recognised file extension, so as to either read successfully or to show +relevant error messages. + + You can also force a specific reader/format by prefixing the file +path with the format and a colon. Eg, to read a .dat file containing +tab separated values: + +$ hledger -f tsv:/some/file.dat stats + + +File: hledger.info, Node: Standard input, Next: Multiple files, Prev: Data formats, Up: Input + +2.3 Standard input +================== + +The file name '-' means standard input: + +$ cat FILE | hledger -f- print + + If reading non-journal data in this way, you'll need to write the +format as a prefix, like 'timeclock:' here: + +$ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:- + + +File: hledger.info, Node: Multiple files, Next: Strict mode, Prev: Standard input, Up: Input + +2.4 Multiple files +================== + +You can specify multiple '-f' options, to read multiple files as one big +journal. When doing this, note that certain features (described below) +will be affected: + + * Balance assertions will not see the effect of transactions in + previous files. (Usually this doesn't matter as each file will set + the corresponding opening balances.) + * Some directives will not affect previous or subsequent files. + + If needed, you can work around these by using a single parent file +which includes the others, or concatenating the files into one, eg: 'cat +a.journal b.journal | hledger -f- CMD'. + + +File: hledger.info, Node: Strict mode, Prev: Multiple files, Up: Input + +2.5 Strict mode +=============== + +hledger checks input files for valid data. By default, the most +important errors are detected, while still accepting easy journal files +without a lot of declarations: + + * Are the input files parseable, with valid syntax ? + * Are all transactions balanced ? + * Do all balance assertions pass ? + + With the '-s'/'--strict' flag, additional checks are performed: + + * Are all accounts posted to, declared with an 'account' directive ? + (Account error checking) + * Are all commodities declared with a 'commodity' directive ? + (Commodity error checking) + * Are all commodity conversions declared explicitly ? + + You can use the check command to run individual checks - the ones +listed above and some more. + + +File: hledger.info, Node: Commands, Next: Options, Prev: Input, Up: Top + +3 Commands +********** + +hledger provides various subcommands for getting things done. Most of +these commands do not change the journal file; they just read it and +output a report. A few commands assist with adding data and file +management. Some often-used commands are 'add', 'print', 'register', +'balancesheet' and 'incomestatement'. + + To show a summary of commands, run 'hledger' with no arguments. You +can see the same commands summary at the start of PART 4: COMMANDS +below. + + To use a particular command, run 'hledger CMD [CMDOPTS] [CMDARGS]', + + * CMD is the full command name, or its standard abbreviation shown in + the commands list, or any unambiguous prefix of the name. + + * CMDOPTS are command-specific options, if any. Command-specific + options must be written after the command name. Eg: 'hledger print + -x'. + + * CMDARGS are additional arguments to the command, if any. Most + hledger commands accept arguments representing a query, to limit + the data in some way. Eg: 'hledger reg assets:checking'. + + To list a command's options, arguments, and documentation in the +terminal, run 'hledger CMD -h'. Eg: 'hledger bal -h'. + +* Menu: + +* Add-on commands:: + + +File: hledger.info, Node: Add-on commands, Up: Commands + +3.1 Add-on commands +=================== + +In addition to the built-in commands, you can install _add-on commands_, +which will also appear in hledger's commands list. Some of these can be +installed as separate packages; others can be found in hledger's bin/ +directory, documented at https://hledger.org/scripts.html. + + 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 directly: 'hledger-ui --watch'. + + Or you can run them with hledger, like built-in commands: 'hledger ui +--watch'. In this case hledger's config file will be used, so you can +set custom options for the addon there. (Before hledger 1.50, an '--' +argument was needed before addon options, but not any more.) + + +File: hledger.info, Node: Options, Next: Output, Prev: Commands, Up: Top + +4 Options +********* + +Run 'hledger -h' to see general command line help. Options can be +written either before or after the command name. These options are +specific to the 'hledger' CLI: + +Flags: + --conf=CONFFILE Use extra options defined in this config file. If + not specified, searches upward and in XDG config + dir for hledger.conf (or .hledger.conf in $HOME). + -n --no-conf ignore any config file + + And the following general options are common to most hledger +commands: + +General input/data transformation flags: + -f --file=[FMT:]FILE Read data from FILE, or from stdin if FILE is -, + inferring format from extension or a FMT: prefix. + Can be specified more than once. If not specified, + reads from $LEDGER_FILE or $HOME/.hledger.journal. + --rules=RULESFILE Use rules defined in this rules file for + converting subsequent CSV/SSV/TSV files. If not + specified, uses FILE.csv.rules for each FILE.csv. + --alias=A=B|/RGX/=RPL transform account names from A to B, or by + replacing regular expression matches + --auto generate extra postings by applying auto posting + rules ("=") to all transactions + --forecast[=PERIOD] Generate extra transactions from periodic rules + ("~"), from after the latest ordinary transaction + until 6 months from now. Or, during the specified + PERIOD (the equals is required). Auto posting rules + will also be applied to these transactions. In + hledger-ui, also make future-dated transactions + visible at startup. + -I --ignore-assertions don't check balance assertions by default + --txn-balancing=... how to check that transactions are balanced: + 'old': use global display precision + 'exact': use transaction precision (default) + --infer-costs infer conversion equity postings from costs + --infer-equity infer costs from conversion equity postings + --infer-market-prices infer market prices from costs + --pivot=TAGNAME use a different field or tag as account names + -s --strict do extra error checks (and override -I) + --verbose-tags add tags indicating generated/modified data + +General output/reporting flags (supported by some commands): + -b --begin=DATE include postings/transactions on/after this date + -e --end=DATE include postings/transactions before this date + (with a report interval, will be adjusted to + following subperiod end) + -D --daily multiperiod report with 1 day interval + -W --weekly multiperiod report with 1 week interval + -M --monthly multiperiod report with 1 month interval + -Q --quarterly multiperiod report with 1 quarter interval + -Y --yearly multiperiod report with 1 year interval + -p --period=PERIODEXP set begin date, end date, and/or report interval, + with more flexibility + --today=DATE override today's date (affects relative dates) + --date2 match/use secondary dates instead (deprecated) + -U --unmarked include only unmarked postings/transactions + -P --pending include only pending postings/transactions + -C --cleared include only cleared postings/transactions + (-U/-P/-C can be combined) + -R --real include only non-virtual postings + -E --empty Show zero items, which are normally hidden. + In hledger-ui & hledger-web, do the opposite. + --depth=DEPTHEXP if a number (or -NUM): show only top NUM levels + of accounts. If REGEXP=NUM, only apply limiting to + accounts matching the regular expression. + -B --cost show amounts converted to their cost/sale amount + -V --market Show amounts converted to their value at period + end(s) in their default valuation commodity. + Equivalent to --value=end. + -X --exchange=COMM Show amounts converted to their value at period + end(s) in the specified commodity. + Equivalent to --value=end,COMM. + --value=WHEN[,COMM] show amounts converted to their value on the + specified date(s) in their default valuation + commodity or a specified commodity. WHEN can be: + 'then': value on transaction dates + 'end': value at period end(s) + 'now': value today + YYYY-MM-DD: value on given date + -c --commodity-style=S Override a commodity's display style. + Eg: -c '.' or -c '1.000,00 EUR' + --pretty[=YN] Use box-drawing characters in text output? Can be + 'y'/'yes' or 'n'/'no'. + If YN is specified, the equals is required. + +General help flags: + -h --help show command line help + --tldr show command examples with tldr + --info show the manual with info + --man show the manual with man + --version show version information + --debug=[1-9] show this much debug output (default: 1) + --pager=YN use a pager when needed ? y/yes (default) or n/no + --color=YNA --colour use ANSI color ? y/yes, n/no, or auto (default) + + Usually hledger accepts any unambiguous flag prefix, eg you can write +'--tl' instead of '--tldr' or '--dry' instead of '--dry-run'. + + You can combine short flags which don't take arguments, eg you can +write '-MAST' instead of '-M -A -S -T'. Flags requiring an argument +can't be combined in this way ('-If FILE' won't work). + + If the same option appears more than once in a command line, usually +the last (right-most) wins. Similarly, if mutually exclusive flags are +used together, the right-most wins. (When flags are mutually exclusive, +they'll usually have a group prefix in -help.) + + With most commands, arguments are interpreted as a hledger query +which filter the data. Some queries can be expressed either with +options or with arguments. + + Below are more tips for using the command line interface - feel free +to skip these until you need them. + +* Menu: + +* Special characters:: +* Unicode characters:: +* Regular expressions:: +* Argument files:: +* Config files:: +* Shell completions:: + + +File: hledger.info, Node: Special characters, Next: Unicode characters, Up: Options + +4.1 Special characters +====================== + +In commands you type at the command line, certain characters have +special meaning and sometimes need to be "escaped" or "quoted", by +prefixing backslashes or enclosing in quotes. + + If you are able to minimise the use of special characters in your +data, you won't have to deal with this as much. For example, you could +use hyphen '-' or underscore '_' instead of spaces in account names, and +you could use the 'USD' currency code instead of the '$' currency symbol +in amounts. + + But if you prefer to use spaced account names and '$', it's fine. +Just be aware of this topic so you can check this doc when needed. +(These examples are mostly tested on unix; some details might need to be +adapted if you're on Windows.) + +* Menu: + +* Escaping shell special characters:: +* Escaping regular expression special characters:: +* Escaping in other situations:: + + +File: hledger.info, Node: Escaping shell special characters, Next: Escaping regular expression special characters, Up: Special characters + +4.1.1 Escaping shell special characters +--------------------------------------- + +These are some characters which may have special meaning to your shell +(the program which interprets command lines): + + * SPACE, '<', '>', '(', ')', '|', '\', '%' + * '$' if followed by a word character + + So for example, to match an account name containing spaces, like +"credit card", don't write: + +$ hledger register credit card + + Instead, enclose the name in single quotes: + +$ hledger register 'credit card' + + On unix or in Windows powershell, if you use double quotes your shell +will silently treat '$' as variable interpolation. So you should +probably avoid double quotes, unless you want that behaviour, eg in a +script: + +$ hledger register "assets:$SOMEACCT" + + But in an older Windows CMD.EXE window, you must use double quotes: + +C:\Users\Me> hledger register "credit card" + + On unix or in Windows powershell, as an alternative to quotes you can +write a backslash before each special character: + +$ hledger register credit\ card + + Finally, since hledger's query arguments are regular expressions +(described below), you could also fill that gap with '.' which matches +any character: + +$ hledger register credit.card + + +File: hledger.info, Node: Escaping regular expression special characters, Next: Escaping in other situations, Prev: Escaping shell special characters, Up: Special characters + +4.1.2 Escaping regular expression special characters +---------------------------------------------------- + +Some characters also have special meaning in regular expressions, which +hledger's arguments often are. Those include: + + * '.', '^', '$', '[', ']', '(', ')', '|', '\' + + To escape one of these, write '\' before it. But note this is in +addition to the shell escaping above. So for characters which are +special to both shell and regular expressions, like '\' and '$', you +will sometimes need two levels of escaping. + + For example, a balance report that uses a 'cur:' query restricting it +to just the $ currency, should be written like this: + +$ hledger balance cur:\\$ + + Explanation: + + 1. Add a backslash '\' before the dollar sign '$' to protect it from + regular expressions (so it will be matched literally with no + special meaning). + 2. Add another backslash before that backslash, to protect it from the + shell (so the shell won't consume it). + 3. '$' doesn't need to be protected from the shell in this case, + because it's not followed by a word character; but it would be + harmless to do so. + + But here's another way to write that, which tends to be easier: add +backslashes to escape from regular expressions, then enclose with quotes +to escape from the shell: + +$ hledger balance cur:'\$' + + +File: hledger.info, Node: Escaping in other situations, Prev: Escaping regular expression special characters, Up: Special characters + +4.1.3 Escaping in other situations +---------------------------------- + +hledger options and arguments are sometimes used in places other than +the command line, where the escaping/quoting rules are different. For +example, backslash-quoting may not be available. Here's a quick +reference: + +In unix shell Use single quotes and/or backslash (or double quotes + for variable interpolation) +In Windows Use single quotes (or double quotes for variable +'powershell' interpolation) +In Windows 'cmd' Use double quotes +In hledger-ui's Use single or double quotes +filter prompt +In hledger-web's Use single or double quotes +search form +In an argument Don't use spaces, don't shell-escape, do +file regex-escape, write one argument/option per line +In a config file Use single or double quotes, and enclose the whole + argument (''desc:a b'' not 'desc:'a b'') +In 'ghci' (the Use double quotes, and enclose the whole argument +Haskell REPL) + + +File: hledger.info, Node: Unicode characters, Next: Regular expressions, Prev: Special characters, Up: Options + +4.2 Unicode characters +====================== + +hledger is expected to handle non-ascii characters correctly: + + * they should be parsed correctly in input files and on the command + line, by all hledger tools (add, iadd, hledger-web's + search/add/edit forms, etc.) + + * they should be displayed correctly by all hledger tools, and + on-screen alignment should be preserved. + + This requires a well-configured environment. Here are some tips: + + * A system locale must be configured, which can decode the characters + being used. This is essential - see Text encoding and Install: + Text encoding. + + * Your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) + must support unicode. On Windows, you may need to use Windows + Terminal. + + * The terminal must be using a font which includes the required + unicode glyphs. + + * The terminal should be configured to display wide characters as + double width (for report alignment). + + * On Windows, for best results you should run hledger in the same + kind of environment in which it was built. Eg hledger built in the + standard CMD.EXE environment (like the binaries on our download + page) might show display problems when run in a cygwin or msys + terminal, and vice versa. (See eg #961). + + +File: hledger.info, Node: Regular expressions, Next: Argument files, Prev: Unicode characters, Up: Options + +4.3 Regular expressions +======================= + +A regular expression (regexp) is a small piece of text where certain +characters (like '.', '^', '$', '+', '*', '()', '|', '[]', '\') have +special meanings, forming a tiny language for matching text precisely - +very useful in hledger and elsewhere. To learn all about them, visit +regular-expressions.info. + + hledger supports regexps whenever you are entering a pattern to match +something, eg in query arguments, account aliases, CSV if rules, +hledger-web's search form, hledger-ui's '/' search, etc. You may need +to wrap them in quotes, especially at the command line (see Special +characters above). Here are some examples: + + Account name queries (quoted for command line use): + +Regular expression: Matches: +------------------- ------------------------------------------------------------ +bank assets:bank, assets:bank:savings, expenses:art:banksy, ... +:bank assets:bank:savings, expenses:art:banksy +:bank: assets:bank:savings +'^bank' none of those ( ^ matches beginning of text ) +'bank$' assets:bank ( $ matches end of text ) +'big \$ bank' big $ bank ( \ disables following character's special meaning ) +'\bbank\b' assets:bank, assets:bank:savings ( \b matches word boundaries ) +'(sav|check)ing' saving or checking ( (|) matches either alternative ) +'saving|checking' saving or checking ( outer parentheses are not needed ) +'savings?' saving or savings ( ? matches 0 or 1 of the preceding thing ) +'my +bank' my bank, my bank, ... ( + matches 1 or more of the preceding thing ) +'my *bank' mybank, my bank, my bank, ... ( * matches 0 or more of the preceding thing ) +'b.nk' bank, bonk, b nk, ... ( . matches any character ) + + Some other queries: + +desc:'amazon|amzn|audible' Amazon transactions +cur:EUR amounts with commodity symbol containing EUR +cur:'\$' amounts with commodity symbol containing $ +cur:'^\$$' only $ amounts, not eg AU$ or CA$ +cur:....? amounts with 4-or-more-character symbols +tag:.=202[1-3] things with any tag whose value contains 2021, 2022 or 2023 + + Account name aliases: accept '.' instead of ':' as account separator: + +alias /\./=: replaces all periods in account names with colons + + Show multiple top-level accounts combined as one: + +--alias='/^[^:]+/=combined' ( [^:] matches any character other than : ) + + Show accounts with the second-level part removed: + +--alias '/^([^:]+):[^:]+/ = \1' + match a top-level account and a second-level account + and replace those with just the top-level account + ( \1 in the replacement text means "whatever was matched + by the first parenthesised part of the regexp" + + CSV rules: match CSV records containing dining-related MCC codes: + +if \?MCC581[124] + + Match CSV records with a specific amount around the end/start of +month: + +if %amount \b3\.99 +& %date (29|30|31|01|02|03)$ + +* Menu: + +* hledger's regular expressions:: + + +File: hledger.info, Node: hledger's regular expressions, Up: Regular expressions + +4.3.1 hledger's regular expressions +----------------------------------- + +hledger's regular expressions come from the regex-tdfa library. If +they're not doing what you expect, it's important to know exactly what +they support: + + 1. they are case insensitive + 2. they are infix matching (they do not need to match the entire thing + being matched) + 3. they are POSIX ERE (extended regular expressions) + 4. they also support GNU word boundaries ('\b', '\B', '\<', '\>') + 5. backreferences are supported when doing text replacement in account + aliases or CSV rules, where backreferences can be used in the + replacement string to reference capturing groups in the search + regexp. Otherwise, if you write '\1', it will match the digit '1'. + 6. they do not support mode modifiers ('(?s)'), character classes + ('\w', '\d'), or anything else not mentioned above. + 7. they may not (I'm guessing not) properly support right-to-left or + bidirectional text. + + Some things to note: + + * In the 'alias' directive and '--alias' option, regular expressions + must be enclosed in forward slashes ('/REGEX/'). Elsewhere in + hledger, these are not required. + + * In queries, to match a regular expression metacharacter like '$' as + a literal character, prepend a backslash. Eg to search for amounts + with the dollar sign in hledger-web, write 'cur:\$'. + + * On the command line, some metacharacters like '$' have a special + meaning to the shell and so must be escaped at least once more. + See Special characters. + + +File: hledger.info, Node: Argument files, Next: Config files, Prev: Regular expressions, Up: Options + +4.4 Argument files +================== + +You can save a set of command line options and arguments in a file, and +then use them by writing '@FILE.args' as a hledger command argument. +The '.args' file extension is conventional, but not required. In an +argument file, + + * Each line can contain one argument, flag, or option. + * Blank lines or lines beginning with '#' are ignored. + * An option's flag and value should be joined by '='. + * An option value or an argument may contain spaces. Don't use + single or double quotes. + * And generally, use one less level of quoting/escaping than at the + command line. Eg 'cur:\$', not 'cur:\\$' as on the command line. + + For example: + +# cash.args + +assets:cash +assets:charles schwab:sweep +cur:\$ +-c=$1. + +$ hledger bal @cash.args + + +File: hledger.info, Node: Config files, Next: Shell completions, Prev: Argument files, Up: Options + +4.5 Config files +================ + +With hledger 1.40+, you can save extra command line options and +arguments in a more featureful hledger config file. Here's a small +example: + +# General options are listed first, and used with hledger commands that support them. +--pretty + +# Options following a `[COMMAND]` heading are used with that hledger command only. +[print] +--explicit --infer-costs + + To use a config file, specify it with the '--conf' option. Its +options will be inserted near the start of your command line, so you can +override them with command line options if needed. + + Or, you can set up an automatic config file that is used whenever you +run hledger, by creating 'hledger.conf' in the current directory or +above, or '.hledger.conf' in your home directory ('~/.hledger.conf'), or +'hledger.conf' in your XDG config directory +('~/.config/hledger/hledger.conf'). + + Here is another example config you could start with: +https://github.com/simonmichael/hledger/blob/master/hledger.conf.sample + + You can put not only options, but also arguments in a config file. +If the first word in a config file's top (general) section does not +begin with a dash (eg: 'print'), it is treated as the command argument +(overriding any argument on the command line). + + On unix machines, you can add a shebang line at the top of a config +file, set executable permission on the file, and use it like a script. +Eg (the '-S' is needed on some operating systems): + +#!/usr/bin/env -S hledger --conf + + You can ignore config files by adding the '-n'/'--no-conf' flag to +the command line. This is useful when using hledger in scripts, or when +troubleshooting. When both '--conf' and '--no-conf' options are used, +the right-most wins. + + To inspect the processing of config files, use '--debug' or +'--debug=8'. Or, run the 'setup' command, which will display any active +config files. ('setup' is not affected by config files itself, unlike +other commands.) + + *Warning!* + + There aren't many hledger features that need a warning, but this is +one! + + Automatic config files, while convenient, also make hledger less +predictable and dependable. It's easy to make a config file that +changes a report's behaviour, or breaks your hledger-using +scripts/applications, in ways that will surprise you later. + + If you don't want this, + + 1. Just don't create a hledger.conf file on your machine. + 2. Also be alert to downloaded directories which may contain a + hledger.conf file. + 3. Also if you are sharing scripts or examples or support, consider + that others may have a hledger.conf file. + + Conversely, once you decide to use this feature, try to remember: + + 1. Whenever a hledger command does not work as expected, try it again + with '-n' ('--no-conf') to see if a config file was to blame. + 2. Whenever you call hledger from a script, consider whether that call + should use '-n' or not. + 3. Be conservative about what you put in your config file; try to + consider the effect on all your reports. + 4. To troubleshoot the effect of config files, run with '--debug' or + '--debug 8'. + + The config file feature was added in hledger 1.40. + + +File: hledger.info, Node: Shell completions, Prev: Config files, Up: Options + +4.6 Shell completions +===================== + +If you use the bash or zsh shells, you can optionally set up +context-sensitive autocompletion for hledger command lines. Try +pressing 'hledger' (should list all hledger commands) +or 'hledger reg acct:' (should list your top-level account +names). If completions aren't working, or for more details, see Install +> Shell completions. + + +File: hledger.info, Node: Output, Next: Environment, Prev: Options, Up: Top + +5 Output +******** + +* Menu: + +* Output destination:: +* Output format:: +* Commodity styles:: +* Debug output:: + + +File: hledger.info, Node: Output destination, Next: Output format, Up: Output + +5.1 Output destination +====================== + +hledger commands send their output to the terminal by default. You can +of course redirect this, eg into a file, using standard shell syntax: + +$ hledger print > foo.txt + + Some commands (print, register, stats, the balance commands) also +provide the '-o'/'--output-file' option, which does the same thing +without needing the shell. Eg: + +$ hledger print -o foo.txt +$ hledger print -o - # write to stdout (the default) + + +File: hledger.info, Node: Output format, Next: Commodity styles, Prev: Output destination, Up: Output + +5.2 Output format +================= + +Some commands offer other kinds of output, not just text on the +terminal. Here are those commands and the formats currently supported: + +command txt html csv/tsv fods beancount sql json +------------------------------------------------------------------------------ +aregister Y Y Y Y Y +balance Y Y Y Y Y +balancesheet Y Y Y Y Y +balancesheetequity Y Y Y Y Y +cashflow Y Y Y Y Y +incomestatement Y Y Y Y Y +print Y Y Y Y Y Y Y +register Y Y Y Y Y + + You can also see which output formats a command supports by running +'hledger CMD -h' and looking for the '-O'/'--output-format=FMT' option, + + You can select the output format by using that option: + +$ hledger print -O csv # print CSV to standard output + + or by choosing a suitable filename extension with the +'-o'/'--output-file=FILE.FMT' option: + +$ hledger balancesheet -o foo.csv # write CSV to foo.csv + + The '-O' option can be combined with '-o' to override the file +extension if needed: + +$ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt + + Here are some notes about the various output formats. + +* Menu: + +* Text output:: +* HTML output:: +* CSV / TSV output:: +* FODS output:: +* Beancount output:: +* SQL output:: +* JSON output:: + + +File: hledger.info, Node: Text output, Next: HTML output, Up: Output format + +5.2.1 Text output +----------------- + +This is the default: human readable, plain text report output, suitable +for viewing with a monospace font in a terminal. If your data contains +unicode or wide characters, you'll need a terminal and font that render +those correctly. (This can be challenging on MS Windows.) + + Some reports ('register', 'aregister') will normally use the full +window width. If this isn't working or you want to override it, you can +use the '-w'/'--width' option. + + Balance reports ('balance', 'balancesheet', 'incomestatement'...) +use whatever width they need. Multi-period multi-currency reports can +often be wider than the window. Besides using a pager, helpful +techniques for this situation include '--layout=bare', '-X COMM', +'cur:', '--transpose', '--tree', '--depth', '--drop', switching to html +output, etc. + +* Menu: + +* Box-drawing characters:: +* Colour:: +* Paging:: + + +File: hledger.info, Node: Box-drawing characters, Next: Colour, Up: Text output + +5.2.1.1 Box-drawing characters +.............................. + +hledger draws simple table borders by default, to minimise the risk of +display problems caused by a terminal/font not supporting box-drawing +characters. + + But your terminal and font probably do support them, so we recommend +using the '--pretty' flag to show prettier tables in the terminal. This +is a good flag to add to your hledger config file. + + +File: hledger.info, Node: Colour, Next: Paging, Prev: Box-drawing characters, Up: Text output + +5.2.1.2 Colour +.............. + +hledger tries to automatically detect ANSI colour and text styling +support and use it when appropriate. (Currently, it is used rather +minimally: some reports show negative numbers in red, and help output +uses bold text for emphasis.) + + You can override this by setting the 'NO_COLOR' environment variable +to disable it, or by using the '--color/--colour' option, perhaps in +your config file, with a 'y'/'yes' or 'n'/'no' value to force it on or +off. + + +File: hledger.info, Node: Paging, Prev: Colour, Up: Text output + +5.2.1.3 Paging +.............. + +In unix-like environments, when displaying large output (in any output +format) in the terminal, hledger tries to use a pager when appropriate. +(You can disable this with the '--pager=no' option, perhaps in your +config file.) + + The pager shows one page of text at a time, and lets you scroll +around to see more. While it is active, usually 'SPACE' shows the next +page, 'h' shows help, and 'q' quits. The home/end/page up/page +down/cursor keys, and mouse scrolling, may also work. + + hledger will use the pager specified by the 'PAGER' environment +variable, otherwise 'less' if available, otherwise 'more' if available. +(With one exception: 'hledger help -p TOPIC' will always use 'less', so +that it can scroll to the topic.) + + The pager is expected to display hledger's ANSI colour and text +styling. If you see junk characters, you might need to configure your +pager to handle ANSI codes. Or you could disable colour as described +above. + + If you are using the 'less' pager, hledger automatically appends a +number of options to the 'LESS' variable to enable ANSI colour and a +number of other conveniences. (At the time of writing: -chop-long-lines +-hilite-unread -ignore-case -no-init -quit-at-eof -quit-if-one-screen +-RAW-CONTROL-CHARS -shift=8 -squeeze-blank-lines -use-backslash ). If +these don't work well, you can set your preferred options in the +'HLEDGER_LESS' variable, which will be used instead. + + +File: hledger.info, Node: HTML output, Next: CSV / TSV output, Prev: Text output, Up: Output format + +5.2.2 HTML output +----------------- + +HTML output can be styled by an optional 'hledger.css' file in the same +directory. + + HTML output will be a HTML fragment, not a complete HTML document. +Like other hledger output, for non-ascii characters it will use the +system locale's text encoding (see Text encoding). + + +File: hledger.info, Node: CSV / TSV output, Next: FODS output, Prev: HTML output, Up: Output format + +5.2.3 CSV / TSV output +---------------------- + +In CSV or TSV output, digit group marks (such as thousands separators) +are disabled automatically. + + +File: hledger.info, Node: FODS output, Next: Beancount output, Prev: CSV / TSV output, Up: Output format + +5.2.4 FODS output +----------------- + +FODS is the OpenDocument Spreadsheet format as plain XML, as accepted by +LibreOffice and OpenOffice. If you use their spreadsheet applications, +this is better than CSV because it works across locales (decimal point +vs. decimal comma, character encoding stored in XML header, thus no +problems with umlauts), it supports fixed header rows and columns, cell +types (string vs. number vs. date), separation of number and currency +(currency is displayed but the cell type is still a number accessible +for computation), styles (bold), borders. Btw. you can still extract +CSV from FODS/ODS using various utilities like 'libreoffice --headless' +or ods2csv. + + +File: hledger.info, Node: Beancount output, Next: SQL output, Prev: FODS output, Up: Output format + +5.2.5 Beancount output +---------------------- + +This is Beancount's journal format. You can use this to export your +hledger data to Beancount, eg to use the Fava web app. + + hledger will try to adjust your data to suit Beancount, +automatically. Be cautious and check the conversion until you are +confident it is good. If you plan to export to Beancount often, you may +want to follow its conventions, for a cleaner conversion: + + * use Beancount-friendly account names + * use currency codes instead of currency symbols + * use cost notation instead of equity conversion postings + * avoid virtual postings, balance assignments, and secondary dates. + + There is one big adjustment you must handle yourself: for Beancount, +the top level account names must be 'Assets', 'Liabilities', 'Equity', +'Income', and/or 'Expenses'. You can use account aliases to rewrite +your account names temporarily, if needed, as in this +hledger2beancount.conf config file. + + 2024-12-20: Some more things not yet handled for you: + + * P directives are not converted automatically - convert those + yourself. + * Balance assignments are not converted (Beancount doesn't support + them) - replace those with explicit amounts. + +* Menu: + +* Beancount account names:: +* Beancount commodity names:: +* Beancount virtual postings:: +* Beancount metadata:: +* Beancount costs:: +* Beancount operating currency:: + + +File: hledger.info, Node: Beancount account names, Next: Beancount commodity names, Up: Beancount output + +5.2.5.1 Beancount account names +............................... + +Aside from the top-level names, hledger will adjust your account names +to make valid Beancount account names, by capitalising each part, +replacing spaces with '-', replacing other unsupported characters with +'C', prepending 'A' to account name parts which don't begin +with a letter or digit, and appending ':A' to account names which have +only one part. + + +File: hledger.info, Node: Beancount commodity names, Next: Beancount virtual postings, Prev: Beancount account names, Up: Beancount output + +5.2.5.2 Beancount commodity names +................................. + +hledger will adjust your commodity names to make valid Beancount +commodity/currency names, which must be 2-24 uppercase letters, digits, +or ''', '.', '_', '-', beginning with a letter and ending with a letter +or digit. hledger will convert known currency symbols to ISO 4217 +currency codes, capitalise letters, replace spaces with '-', replace +other unsupported characters with 'C', and prepend or append +'C' if needed. + + +File: hledger.info, Node: Beancount virtual postings, Next: Beancount metadata, Prev: Beancount commodity names, Up: Beancount output + +5.2.5.3 Beancount virtual postings +.................................. + +Beancount doesn't allow virtual postings; if you have any, they will be +omitted from beancount output. + + +File: hledger.info, Node: Beancount metadata, Next: Beancount costs, Prev: Beancount virtual postings, Up: Beancount output + +5.2.5.4 Beancount metadata +.......................... + +hledger tags will be converted to Beancount metadata (except for tags +whose name begins with '_'). Metadata names will be adjusted to be +Beancount-compatible: beginning with a lowercase letter, at least two +characters long, and with unsupported characters encoded. Metadata +values will use Beancount's string type. + + In hledger, objects can have the same tag repeated with multiple +values. Eg an 'assets:cash' account might have both 'type:Asset' and +'type:Cash' tags. For Beancount these will be combined into one, with +the values combined, comma separated. Eg: 'type: "Asset, Cash"'. + + +File: hledger.info, Node: Beancount costs, Next: Beancount operating currency, Prev: Beancount metadata, Up: Beancount output + +5.2.5.5 Beancount costs +....................... + +Beancount doesn't allow redundant costs and conversion postings as +hledger does. If you have any of these, the conversion postings will be +omitted. Currently we support at most one cost + conversion postings +group per transaction. + + +File: hledger.info, Node: Beancount operating currency, Prev: Beancount costs, Up: Beancount output + +5.2.5.6 Beancount operating currency +.................................... + +Declaring an operating currency (or several) improves Beancount and Fava +reports. Currently hledger will declare each currency used in cost +amounts as an operating currency. If needed, replace these with your +own declaration, like + +option "operating_currency" "USD" + + +File: hledger.info, Node: SQL output, Next: JSON output, Prev: Beancount output, Up: Output format + +5.2.6 SQL output +---------------- + +SQL output is expected to work at least with SQLite, MySQL and Postgres. + + The SQL statements are expected to be executed in the empty database. +If you already have tables created via SQL output of hledger, you would +probably want to either clear data from these (via 'delete' or +'truncate' SQL statements) or 'drop' the tables completely before +import; otherwise your postings would be duplicated. + + For SQLite, it is more useful if you modify the generated 'id' field +to be a PRIMARY KEY. Eg: + +$ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ... + + This is not yet much used; feedback is welcome. + + +File: hledger.info, Node: JSON output, Prev: SQL output, Up: Output format + +5.2.7 JSON output +----------------- + +Our JSON is rather large and verbose, since it is a faithful +representation of hledger's internal data types. To understand its +structure, read the Haskell type definitions, which are mostly in +https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs. +hledger-web's OpenAPI specification may also be relevant. + + hledger stores numbers with sometimes up to 255 significant digits. +This is too many digits for most JSON consumers, so in JSON output we +round numbers to at most 10 decimal places. (We don't limit the number +of integer digits.) If you find this causing problems, please let us +know. Related: #1195 + + This is not yet much used; feedback is welcome. + + +File: hledger.info, Node: Commodity styles, Next: Debug output, Prev: Output format, Up: Output + +5.3 Commodity styles +==================== + +When displaying amounts, hledger infers a standard display style for +each commodity/currency, as described below in Commodity display style. + + If needed, this can be overridden by a '-c/--commodity-style' option +(except for cost amounts and amounts displayed by the 'print' command, +which are always displayed with all decimal digits). For example, the +following will force dollar amounts to be displayed as shown: + +$ hledger print -c '$1.000,0' + + This option can be repeated to set the display style for multiple +commodities/currencies. Its argument is as described in the commodity +directive. + + In some cases hledger will adjust number formatting to improve their +parseability (such as adding trailing decimal marks when needed). + + +File: hledger.info, Node: Debug output, Prev: Commodity styles, Up: Output + +5.4 Debug output +================ + +We intend hledger to be relatively easy to troubleshoot, introspect and +develop. You can add '--debug[=N]' to any hledger command line to see +additional debug output. N ranges from 1 (least output, the default) to +9 (maximum output). Typically you would start with 1 and increase until +you are seeing enough. Debug output goes to stderr, and is not affected +by '-o/--output-file' (unless you redirect stderr to stdout, eg: +'2>&1'). It will be interleaved with normal output, which can help +reveal when parts of the code are evaluated. To capture debug output in +a log file instead, you can usually redirect stderr, eg: + +hledger bal --debug=3 2>hledger.log + + (This option doesn't work in a config file yet.) + + +File: hledger.info, Node: Environment, Next: PART 2 DATA FORMATS, Prev: Output, Up: Top + +6 Environment +************* + +These environment variables affect hledger: + + *HLEDGER_LESS* If 'less' is your pager, this variable specifies the +'less' options hledger should use. (Otherwise, 'LESS' + custom options +are used.) + + *LEDGER_FILE* The default journal file, to be used when no +'-f/--file' option is provided. For example, it could be +'~/finance/main.journal'. This can also be a glob pattern, eg +'./2???.journal'. (If the glob matches multiple files, only the +alphanumerically first one is used.) If LEDGER_FILE points to a +non-existent file, an error will be raised. If the value is the empty +string, it is ignored. + + If LEDGER_FILE is not set and '-f' is not provided, the default +journal file is '$HOME/.hledger.journal' (or if a home directory can't +be detected, './.hledger.journal'). + + See also Common tasks > Setting LEDGER_FILE. + + *NO_COLOR* If this environment variable exists (with any value, +including empty), hledger will not use ANSI color codes in terminal +output, unless overridden by an explicit '--color=y' or '--colour=y' +option. + + +File: hledger.info, Node: PART 2 DATA FORMATS, Next: Journal, Prev: Environment, Up: Top + +7 PART 2: DATA FORMATS +********************** + + +File: hledger.info, Node: Journal, Next: CSV, Prev: PART 2 DATA FORMATS, Up: Top + +8 Journal +********* + +hledger's usual data source is a plain text file containing journal +entries in hledger 'journal' format. If you're looking for a quick +reference, jump ahead to the journal cheatsheet (or use the table of +contents at https://hledger.org/hledger.html). + + This file represents an accounting General Journal. The '.journal' +file extension is most often used, though not strictly required. The +journal file contains a number of transaction entries, each describing a +transfer of money (or any commodity) between two or more named accounts, +in a simple format readable by both hledger and humans. + + hledger's journal format is compatible with most of Ledger's journal +format, but not all of it. The differences and interoperation tips are +described at hledger and Ledger. With some care, and by avoiding +incompatible features, you can keep your hledger journal readable by +Ledger and vice versa. This can useful eg for comparing the behaviour +of one app against the other. + + You can use hledger without learning any more about this file; just +use the add or web or import commands to create and update it. + + Many users, though, edit the journal file with a text editor, and +track changes with a version control system such as git. Editor add-ons +such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and +hledger-vscode for Visual Studio Code, make this easier, adding colour, +formatting, tab completion, and useful commands. See Editor +configuration at hledger.org for the full list. + + A hledger journal file can contain three kinds of thing: comment +lines, transactions, and/or directives (including periodic transaction +rules and auto posting rules). Understanding the journal file format +will also give you a good understanding of hledger's data model. Here's +a quick cheatsheet/overview, followed by detailed descriptions of each +part. + +* Menu: + +* Journal cheatsheet:: +* Comments:: +* Transactions:: +* Dates:: +* Status:: +* Code:: +* Description:: +* Transaction comments:: +* Postings:: +* Account names:: +* Amounts:: +* Balance assertions:: +* Posting comments:: +* Transaction balancing:: +* Tags:: +* Directives:: +* account directive:: +* alias directive:: +* commodity directive:: +* decimal-mark directive:: +* include directive:: +* P directive:: +* payee directive:: +* tag directive:: +* Periodic transactions:: +* Auto postings:: +* Other syntax:: + + +File: hledger.info, Node: Journal cheatsheet, Next: Comments, Up: Journal + +8.1 Journal cheatsheet +====================== + +# Here is the main syntax of hledger's journal format +# (omitting extra Ledger compatibility syntax). + +############################################################################### + +# 1. These are comment lines, for notes or temporarily disabling things. +; They begin with # or ; + +comment +Or, lines can be enclosed within "comment" / "end comment". +This is a block of +commented lines. +end comment + +# Some journal entries can have semicolon comments at end of line ; like this +# Some of them require 2 or more spaces before the semicolon. + +############################################################################### + +# 2. Directives customise processing or output in some way. +# You don't need any directives to get started. +# But they can add more error checking, or change how things are displayed. +# They begin with a word, letter, or symbol. +# They are most often placed at the top, before transactions. + +account assets ; Declare valid account names and display order. +account assets:savings ; A subaccount. This one represents a bank account. +account assets:checking ; Another. Note, 2+ spaces after the account name. +account assets:receivable ; Accounting type is inferred from english names, +account passifs ; or declared with a "type" tag, type:L +account expenses ; type:X + ; A follow-on comment line, indented. +account expenses:rent ; Expense and revenue categories are also accounts. + ; Subaccounts inherit their parent's type. + +commodity $0.00 ; Declare valid commodities and their display styles. +commodity 1.000,00 EUR + +decimal-mark . ; The decimal mark used in this file (if ambiguous). + +payee Whole Foods ; Declare a valid payee name. + +tag trip ; Declare a valid tag name. + +P 2024-03-01 AAPL $179 ; Declare a market price for AAPL in $ on this date. + +include other.journal ; Include another journal file here. + +# Declare a recurring "periodic transaction", for budget/forecast reports +~ monthly set budget goals ; <- Note, 2+ spaces before the description. + (expenses:rent) $1000 + (expenses:food) $500 + +# Declare an auto posting rule, to modify existing transactions in reports += revenues:consulting + liabilities:tax:2024:us *0.25 ; Add a tax liability & expense + expenses:tax:2024:us *-0.25 ; for 25% of the revenue. + +############################################################################### + +# 3. Transactions are what it's all about. +# They are dated events, usually movements of money between 2 or more accounts. +# They begin with a numeric date. +# Here is their basic shape: +# +# DATE DESCRIPTION ; The transaction's date and optional description. +# ACCOUNT1 AMOUNT ; A posting of an amount to/from this account, indented. +# ACCOUNT2 AMOUNT ; A second posting, balancing the first. +# ... ; More if needed. Amounts must sum to zero. +# ; Note, 2+ spaces between account names and amounts. + +2024-01-01 opening balances ; At the start, declare pre-existing balances this way. + assets:savings $10000 ; Account names can be anything. lower case is easy to type. + assets:checking $1000 ; assets, liabilities, equity, revenues, expenses are common. + liabilities:credit card $-500 ; liabilities, equity, revenues balances are usually negative. + equity:start ; One amount can be left blank. $-10500 is inferred here. + ; Some of these accounts we didn't declare above, + ; so -s/--strict would complain. + +2024-01-03 ! (12345) pay rent + ; Additional transaction comment lines, indented. + ; There can be a ! or * after the date meaning "pending" or "cleared". + ; There can be a parenthesised (code) after the date/status. + ; Amounts' sign shows direction of flow. + assets:checking $-500 ; Minus means removed from this account (credit). + expenses:rent $500 ; Plus means added to this account (debit). + +; Keeping transactions in date order is optional (but helps error checking). + +2024-01-02 Gringott's Bank | withdrawal ; Description can be PAYEE | NOTE + assets:bank:gold -10 gold + assets:pouch 10 gold + +2024-01-02 shopping + expenses:clothing 1 gold + expenses:wands 5 gold + assets:pouch -6 gold + +2024-01-02 receive gift + revenues:gifts -3 "Chocolate Frogs" ; Complex commodity symbols + assets:pouch 3 "Chocolate Frogs" ; must be in double quotes. + +2024-01-15 buy some shares, in two lots ; Cost can be noted. + assets:investments:2024-01-15 2.0 AAAA @ $1.50 ; @ means per-unit cost + assets:investments:2024-01-15-02 3.0 AAAA @@ $4 ; @@ means total cost + ; ^ Per-lot subaccounts are sometimes useful. + assets:checking $-7 + +2024-01-15 assert some account balances on this date + ; Balances can be asserted in any transaction, with =, for extra error checking. + ; Assertion txns like this one can be made with hledger close --assert --show-costs + ; + assets:savings $0 = $10000 + assets:checking $0 = $493 + assets:bank:gold 0 gold = -10 gold + assets:pouch 0 gold = 4 gold + assets:pouch 0 "Chocolate Frogs" = 3 "Chocolate Frogs" + assets:investments:2024-01-15 0.0 AAAA = 2.0 AAAA @ $1.50 + assets:investments:2024-01-15-02 0.0 AAAA = 3.0 AAAA @@ $4 + liabilities:credit card $0 = $-500 + +2024-02-01 note some event, or a transaction not yet fully entered, on this date + ; Postings are not required. + +# Consistent YYYY-MM-DD date format is recommended, +# but you can use . or / and omit leading zeros if you prefer. +2024.01.01 +2024/1/1 + + +File: hledger.info, Node: Comments, Next: Transactions, Prev: Journal cheatsheet, Up: Journal + +8.2 Comments +============ + +Lines in the journal will be ignored if they begin with a hash ('#') or +a semicolon (';'). (See also Other syntax.) hledger will also ignore +regions beginning with a 'comment' line and ending with an 'end comment' +line (or file end). Here's a suggestion for choosing between them: + + * '#' for top-level notes + * ';' for commenting out things temporarily + * 'comment' for quickly commenting large regions (remember it's + there, or you might get confused) + + Eg: + +# a comment line +; another commentline +comment +A multi-line comment block, +continuing until "end comment" directive +or the end of the current file. +end comment + + Some hledger entries can have same-line comments attached to them, +from ; (semicolon) to end of line. See Transaction comments, Posting +comments, and Account comments below. + + +File: hledger.info, Node: Transactions, Next: Dates, Prev: Comments, Up: Journal + +8.3 Transactions +================ + +Transactions are the main unit of information in a journal file. They +represent events, typically a movement of some quantity of commodities +between two or more named accounts. + + Each transaction is recorded as a journal entry, beginning with a +simple date in column 0. This can be followed by any of the following +optional fields, separated by spaces: + + * a status character (empty, '!', or '*') + * a code (any short number or text, enclosed in parentheses) + * a description (any remaining text until end of line or a semicolon) + * a comment (any remaining text following a semicolon until end of + line, and any following indented lines beginning with a semicolon) + * 0 or more indented _posting_ lines, describing what was transferred + and the accounts involved (indented comment lines are also allowed, + but not blank lines or non-indented lines). + + Here's a simple journal file containing one transaction: + +2008/01/01 income + assets:bank:checking $1 + income:salary $-1 + + +File: hledger.info, Node: Dates, Next: Status, Prev: Transactions, Up: Journal + +8.4 Dates +========= + +* Menu: + +* Simple dates:: +* Posting dates:: + + +File: hledger.info, Node: Simple dates, Next: Posting dates, Up: Dates + +8.4.1 Simple dates +------------------ + +Dates in the journal file use _simple dates_ format: 'YYYY-MM-DD' or +'YYYY/MM/DD' or 'YYYY.MM.DD', with leading zeros optional. The year may +be omitted, in which case it will be inferred from the context: the +current transaction, the default year set with a 'Y' directive, or the +current date when the command is run. Some examples: '2010-01-31', +'2010/01/31', '2010.1.31', '1/31'. + + (The UI also accepts simple dates, as well as the more flexible smart +dates documented in the hledger manual.) + + +File: hledger.info, Node: Posting dates, Prev: Simple dates, Up: Dates + +8.4.2 Posting dates +------------------- + +You can give individual postings a different date from their parent +transaction, by adding a posting comment containing a tag (see below) +like 'date:DATE'. This is probably the best way to control posting +dates precisely. Eg in this example the expense should appear in May +reports, and the deduction from checking should be reported on 6/1 for +easy bank reconciliation: + +2015/5/30 + expenses:food $10 ; food purchased on saturday 5/30 + assets:checking ; bank cleared it on monday, date:6/1 + +$ hledger -f t.j register food +2015-05-30 expenses:food $10 $10 + +$ hledger -f t.j register checking +2015-06-01 assets:checking $-10 $-10 + + DATE should be a simple date; if the year is not specified it will +use the year of the transaction's date. +The 'date:' tag must have a valid simple date value if it is present, eg +a 'date:' tag with no value is not allowed. + + +File: hledger.info, Node: Status, Next: Code, Prev: Dates, Up: Journal + +8.5 Status +========== + +Transactions (or individual postings within a transaction) can have a +status mark, which is a single character before the transaction +description (or posting account name), separated from it by a space, +indicating one of three statuses: + +mark status + +----------------- + unmarked +'!' pending +'*' cleared + + When reporting, you can filter by status with the '-U/--unmarked', +'-P/--pending', and '-C/--cleared' flags (and you can combine these, eg +'-UP' to match all except cleared things). Or you can use the +'status:', 'status:!', and 'status:*' queries, or the U, P, C keys in +hledger-ui. + + (Note: in Ledger the "unmarked" state is called "uncleared"; in +hledger we renamed it to "unmarked" for semantic clarity.) + + Status marks are optional, but can be helpful eg for reconciling with +real-world accounts. Some editor modes provide highlighting and +shortcuts for working with status. Eg in Emacs ledger-mode, you can +toggle transaction status with C-c C-e, or posting status with C-c C-c. + + What "uncleared", "pending", and "cleared" actually mean is up to +you. Here's one suggestion: + +status meaning +-------------------------------------------------------------------------- +uncleared recorded but not yet reconciled; needs review +pending tentatively reconciled (if needed, eg during a big + reconciliation) +cleared complete, reconciled as far as possible, and considered + correct + + With this scheme, you would use '-PC' to see the current balance at +your bank, '-U' to see things which will probably hit your bank soon +(like uncashed checks), and no flags to see the most up-to-date state of +your finances. + + +File: hledger.info, Node: Code, Next: Description, Prev: Status, Up: Journal + +8.6 Code +======== + +After the status mark, but before the description, you can optionally +write a transaction "code", enclosed in parentheses. This is a good +place to record a check number, or some other important transaction id +or reference number. + + +File: hledger.info, Node: Description, Next: Transaction comments, Prev: Code, Up: Journal + +8.7 Description +=============== + +After the date, status mark and/or code fields, the rest of the line (or +until a comment is begun with ';') is the transaction's description. +Here you can describe the transaction (called the "narration" in +traditional bookkeeping), or you can record a payee/payer name, or you +can leave it empty. + + Transaction descriptions show up in print output and in register +reports, and can be listed with the descriptions command. + + You can query by description with 'desc:DESCREGEX', or pivot on +description with '--pivot desc'. + +* Menu: + +* Payee and note:: + + +File: hledger.info, Node: Payee and note, Up: Description + +8.7.1 Payee and note +-------------------- + +Sometimes people want a dedicated payee/payer field that can be queried +and checked more strictly. If you want that, you can write a '|' (pipe) +character in the description. This divides it into a "payee" field on +the left, and a "note" field on the right. (Either can be empty.) + + You can query these with 'payee:PAYEEREGEX' and 'note:NOTEREGEX', +list their values with the payees and notes commands, or pivot on +'payee' or 'note'. + + Note: in transactions with no '|' character, description, payee, and +note all have the same value. Once a '|' is added, they become +distinct. (If you'd like to change this behaviour, please propose it on +the mail list.) + + If you want more strict error checking, you can declare the valid +payee names with payee directives, and then enforce these with hledger +check payees. (Note: because of the above, for this you'll need to +ensure every transaction description contains a '|' and therefore a +checkable payee name, even if it's empty.) + + +File: hledger.info, Node: Transaction comments, Next: Postings, Prev: Description, Up: Journal + +8.8 Transaction comments +======================== + +Text following ';', after a transaction description, and/or on indented +lines immediately below it, form comments for that transaction. They +are reproduced by 'print' but otherwise ignored, except they may contain +tags, which are not ignored. + +2012-01-01 something ; a transaction comment + ; a second line of transaction comment + expenses 1 + assets + + +File: hledger.info, Node: Postings, Next: Account names, Prev: Transaction comments, Up: Journal + +8.9 Postings +============ + +A posting is an addition of some amount to, or removal of some amount +from, an account. Each posting line begins with at least one space or +tab (2 or 4 spaces is common), followed by: + + * (optional) a status character (empty, '!', or '*'), followed by a + space + * (required) an account name (any text, optionally containing *single + spaces*, until end of line or a double space) + * (optional) *two or more spaces* (or tabs) followed by an amount. + + If the amount is positive, it is being added to the account; if +negative, it is being removed from the account. + + The posting amounts in a transaction must sum up to zero, indicating +that the inflows and outflows are equal. We call this a balanced +transaction. (You can read more about the nitty-gritty details of "sum +up to zero" in Transaction balancing below.) + + As a convenience, you can optionally leave one amount blank; hledger +will infer what it should be so as to balance the transaction. + +* Menu: + +* Debits and credits:: +* The two space delimiter:: + + +File: hledger.info, Node: Debits and credits, Next: The two space delimiter, Up: Postings + +8.9.1 Debits and credits +------------------------ + +The traditional accounting concepts of debit and credit of course exist +in hledger, but we represent them with numeric sign, as described above. +Positive and negative posting amounts represent debits and credits +respectively. + + You don't need to remember that, but if you would like to - eg for +helping newcomers or for talking with your accountant - here's a handy +mnemonic: + + _'debit / plus / left / short words'_ +_'credit / minus / right / longer words'_ + + +File: hledger.info, Node: The two space delimiter, Prev: Debits and credits, Up: Postings + +8.9.2 The two space delimiter +----------------------------- + +Be sure to notice the unusual separator between the account name and the +following amount. Because hledger allows account names with spaces in +them, you must separate the account name and amount (if any) by *two or +more spaces* (or tabs). It's easy to forget at first. If you ever see +the amount being treated as part of the account name, you'll know you +probably need to add another space between them. + + +File: hledger.info, Node: Account names, Next: Amounts, Prev: Postings, Up: Journal + +8.10 Account names +================== + +Accounts are the main way of categorising things in hledger. As in +Double Entry Bookkeeping, they can represent real world accounts (such +as a bank account), or more abstract categories such as "money borrowed +from Frank" or "money spent on electricity". + + You can use any account names you like, but we usually start with the +traditional accounting categories, which in english are 'assets', +'liabilities', 'equity', 'revenues', 'expenses'. (You might see these +referred to as A, L, E, R, X for short.) + + For more precise reporting, we usually divide the top level accounts +into more detailed subaccounts, by writing a full colon between account +name parts. For example, from the account names 'assets:bank:checking' +and 'expenses:food', hledger will infer this hierarchy of five accounts: + +assets +assets:bank +assets:bank:checking +expenses +expenses:food + + Shown as an outline, the hierarchical tree structure is more clear: + +assets + bank + checking +expenses + food + + hledger reports can summarise the account tree to any depth, so you +can go as deep as you like with subcategories, but keeping your account +names relatively simple may be best when starting out. + + Account names may be capitalised or not; they may contain letters, +numbers, symbols, or single spaces. Note, when an account name and an +amount are written on the same line, they must be separated by *two or +more spaces* (or tabs). + + Parentheses or brackets enclosing the full account name indicate +virtual postings, described below. Parentheses or brackets internal to +the account name have no special meaning. + + Account names can be altered temporarily or permanently by account +aliases. + + +File: hledger.info, Node: Amounts, Next: Balance assertions, Prev: Account names, Up: Journal + +8.11 Amounts +============ + +After the account name, there is usually an amount. (Remember: between +account name and amount, there must be two or more spaces.) + + hledger's amount format is flexible, supporting several international +formats. Here are some examples. Amounts have a number (the +"quantity"): + +1 + + ..and usually a currency symbol or commodity name (more on this +below), to the left or right of the quantity, with or without a +separating space: + +$1 +4000 AAPL +3 "green apples" + + Amounts can be preceded by a minus sign (or a plus sign, though plus +is the default), The sign can be written before or after a left-side +commodity symbol: + +-$1 +$-1 + + One or more spaces between the sign and the number are acceptable +when parsing (but they won't be displayed in output): + ++ $1 +$- 1 + + Scientific E notation is allowed: + +1E-6 +EUR 1E3 + +* Menu: + +* Decimal marks:: +* Digit group marks:: +* Commodity:: +* Costs:: + + +File: hledger.info, Node: Decimal marks, Next: Digit group marks, Up: Amounts + +8.11.1 Decimal marks +-------------------- + +A _decimal mark_ can be written as a period or a comma: + +1.23 +1,23 + + Both of these are common in international number formats, so hledger +is not biased towards one or the other. Because hledger also supports +digit group marks (eg thousands separators), this means that a number +like '1,000' or '1.000' containing just one period or comma is +ambiguous. In such cases, hledger by default assumes it is a decimal +mark, and will parse both of those as 1. + + To help hledger parse such ambiguous numbers more accurately, if you +use digit group marks, we recommend declaring the decimal mark +explicitly. The best way is to add a 'decimal-mark' directive at the +top of each data file, like this: + +decimal-mark . + + Or you can declare it per commodity with 'commodity' directives, +described below. + + hledger also accepts numbers like '10.' with no digits after the +decimal mark (and will sometimes display numbers that way to +disambiguate them - see Trailing decimal marks). + + +File: hledger.info, Node: Digit group marks, Next: Commodity, Prev: Decimal marks, Up: Amounts + +8.11.2 Digit group marks +------------------------ + +In the integer part of the amount quantity (left of the decimal mark), +groups of digits can optionally be separated by a _digit group mark_ - a +comma or period (whichever is not used as decimal mark), or a space +(several Unicode space variants, like no-break space, are also +accepted). So these are all valid amounts in a journal file: + + $1,000,000.00 + EUR 2.000.000,00 +INR 9,99,99,999.00 + 1 000 000.00 ; <- ordinary space + 1 000 000.00 ; <- no-break space + + +File: hledger.info, Node: Commodity, Next: Costs, Prev: Digit group marks, Up: Amounts + +8.11.3 Commodity +---------------- + +Amounts in hledger have both a "quantity", which is a signed decimal +number, and a "commodity", which is a currency symbol, stock ticker, or +any word or phrase describing something you are tracking. + + If the commodity name contains non-letters (spaces, numbers, or +punctuation), you must always write it inside double quotes ('"green +apples"', '"ABC123"'). + + If you write just a bare number, that too will have a commodity, with +name '""'; we call that the "no-symbol commodity". + + Actually, hledger combines these single-commodity amounts into more +powerful multi-commodity amounts, which are what it works with most of +the time. A multi-commodity amount could be, eg: '1 USD, 2 EUR, 3.456 +TSLA'. In practice, you will only see multi-commodity amounts in +hledger's output; you can't write them directly in the journal file. + + By default, the format of amounts in the journal influences how +hledger displays them in output. This is explained in Commodity display +style below. + + +File: hledger.info, Node: Costs, Prev: Commodity, Up: Amounts + +8.11.4 Costs +------------ + +After a posting amount, you can note its cost (when buying) or selling +price (when selling) in another commodity, by writing either '@ +UNITPRICE' or '@@ TOTALPRICE' after it. This indicates a conversion +transaction, where one commodity is exchanged for another. + + (You might also see this called "transaction price" in hledger docs, +discussions, or code; that term was directionally neutral and reminded +that it is a price specific to a transaction, but we now just call it +"cost", with the understanding that the transaction could be a purchase +or a sale.) + + Costs are usually written explicitly with '@' or '@@', but can also +be inferred automatically for simple multi-commodity transactions. +Note, if costs are inferred, the order of postings is significant; the +first posting will have a cost attached, in the commodity of the second. + + As an example, here are several ways to record purchases of a foreign +currency in hledger, using the cost notation either explicitly or +implicitly: + + 1. Write the price per unit, as '@ UNITPRICE' after the amount: + + 2009/1/1 + assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each + assets:dollars ; balancing amount is -$135.00 + + 2. Write the total price, as '@@ TOTALPRICE' after the amount: + + 2009/1/1 + assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot + assets:dollars + + 3. Specify amounts for all postings, using exactly two commodities, + and let hledger infer the price that balances the transaction. + Note the effect of posting order: the price is added to first + posting, making it '€100 @@ $135', as in example 2: + + 2009/1/1 + assets:euros €100 ; one hundred euros purchased + assets:dollars $-135 ; for $135 + + Amounts can be converted to cost at report time using the '-B/--cost' +flag; this is discussed more in the Cost reporting section. + + Note that the cost normally should be a positive amount, though it's +not required to be. This can be a little confusing, see discussion at +-infer-market-prices: market prices from transactions. + + +File: hledger.info, Node: Balance assertions, Next: Posting comments, Prev: Amounts, Up: Journal + +8.12 Balance assertions +======================= + +hledger supports Ledger-style balance assertions in journal files. +These look like, for example, '= EXPECTEDBALANCE' following a posting's +amount. Eg here we assert the expected dollar balance in accounts a and +b after each posting: + +2013/1/1 + a $1 = $1 + b = $-1 + +2013/1/2 + a $1 = $2 + b $-1 = $-2 + + After reading a journal file, hledger will check all balance +assertions and report an error if any of them fail. Balance assertions +can protect you from, eg, inadvertently disrupting reconciled balances +while cleaning up old entries. You can disable them temporarily with +the '-I/--ignore-assertions' flag, which can be useful for +troubleshooting or for reading Ledger files. (Note: this flag currently +does not disable balance assignments, described below). + +* Menu: + +* Assertions and ordering:: +* Assertions and multiple files:: +* Assertions and costs:: +* Assertions and commodities:: +* Assertions and subaccounts:: +* Assertions and status:: +* Assertions and virtual postings:: +* Assertions and auto postings:: +* Assertions and precision:: +* Assertions and hledger add:: + + +File: hledger.info, Node: Assertions and ordering, Next: Assertions and multiple files, Up: Balance assertions + +8.12.1 Assertions and ordering +------------------------------ + +hledger calculates and checks an account's balance assertions in date +order (and when there are multiple assertions on the same day, in parse +order). Note this is different from Ledger, which checks assertions +always in parse order, ignoring dates. + + This means in hledger you can freely reorder transactions, postings, +or files, and balance assertions will usually keep working. The +exception is when you reorder multiple postings on the same day, to the +same account, which have balance assertions; those will likely need +updating. + + +File: hledger.info, Node: Assertions and multiple files, Next: Assertions and costs, Prev: Assertions and ordering, Up: Balance assertions + +8.12.2 Assertions and multiple files +------------------------------------ + +If an account has transactions appearing in multiple files, balance +assertions can still work - but _only if those files are part of a +hierarchy made by include directives_. + + If the same files are specified with two '-f' options on the command +line, the assertions in the second will not see the balances from the +first. + + To work around this, arrange your files in a hierarchy with +'include'. Or, you could concatenate the files temporarily, and process +them like one big file. + + Why does it work this way ? It might be related to hledger's goal of +stable predictable reports. File hierarchy is considered "permanent", +part of your data, while the order of command line options/arguments is +not. We don't want transient changes to be able to change the meaning +of the data. Eg it would be frustrating if tomorrow all your balance +assertions broke because you wrote command line arguments in a different +order. (Discussion welcome.) + + +File: hledger.info, Node: Assertions and costs, Next: Assertions and commodities, Prev: Assertions and multiple files, Up: Balance assertions + +8.12.3 Assertions and costs +--------------------------- + +Balance assertions ignore costs, and should normally be written without +one: + +2019/1/1 + (a) $1 @ €1 = $1 + + We do allow costs to be written in balance assertion amounts, +however, and print shows them, but they don't affect whether the +assertion passes or fails. This is for backward compatibility +(hledger's close command used to generate balance assertions with +costs), and because balance _assignments_ do use costs (see below). + + +File: hledger.info, Node: Assertions and commodities, Next: Assertions and subaccounts, Prev: Assertions and costs, Up: Balance assertions + +8.12.4 Assertions and commodities +--------------------------------- + +The balance assertions described so far are "*single commodity balance +assertions*": they assert and check the balance in one commodity, +ignoring any others that may be present. This is how balance assertions +work in Ledger also. + + If an account contains multiple commodities, you can assert their +balances by writing multiple postings with balance assertions, one for +each commodity: + +2013/1/1 + usd $-1 + eur €-1 + both + +2013/1/2 + both 0 = $1 + both 0 = €1 + + In hledger you can make a stronger "*sole commodity balance +assertion*" by writing two equals signs ('== EXPECTEDBALANCE'). This +also asserts that there are no other commodities in the account besides +the asserted one (or at least, that their current balance is zero): + +2013/1/1 + usd $-1 == $-1 ; these sole commodity assertions succeed + eur €-1 == €-1 + both ;== $1 ; this one would fail because 'both' contains $ and € + + It's less easy to make a "*sole commodities balance assertion*" (note +the plural) - ie, asserting that an account contains two or more +specified commodities and no others. It can be done by + + 1. isolating each commodity in a subaccount, and asserting those + 2. and also asserting there are no commodities in the parent account + itself: + +2013/1/1 + usd $-1 + eur €-1 + both 0 == 0 ; nothing up my sleeve + both:usd $1 == $1 ; a dollar here + both:eur €1 == €1 ; a euro there + + +File: hledger.info, Node: Assertions and subaccounts, Next: Assertions and status, Prev: Assertions and commodities, Up: Balance assertions + +8.12.5 Assertions and subaccounts +--------------------------------- + +All of the balance assertions above (both '=' and '==') are +"*subaccount-exclusive balance assertions*"; they ignore any balances +that exist in deeper subaccounts. + + In hledger you can make "*subaccount-inclusive balance assertions*" +by adding a star after the equals ('=*' or '==*'): + +2019/1/1 + equity:start + assets:checking $10 + assets:savings $10 + assets $0 ==* $20 ; assets + subaccounts contains $20 and nothing else + + +File: hledger.info, Node: Assertions and status, Next: Assertions and virtual postings, Prev: Assertions and subaccounts, Up: Balance assertions + +8.12.6 Assertions and status +---------------------------- + +Balance assertions always consider postings of all statuses (unmarked, +pending, or cleared); they are not affected by the '-U'/'--unmarked' / +'-P'/'--pending' / '-C'/'--cleared' flags or the 'status:' query. + + +File: hledger.info, Node: Assertions and virtual postings, Next: Assertions and auto postings, Prev: Assertions and status, Up: Balance assertions + +8.12.7 Assertions and virtual postings +-------------------------------------- + +Balance assertions always consider both real and virtual postings; they +are not affected by the '--real/-R' flag or 'real:' query. + + +File: hledger.info, Node: Assertions and auto postings, Next: Assertions and precision, Prev: Assertions and virtual postings, Up: Balance assertions + +8.12.8 Assertions and auto postings +----------------------------------- + +Balance assertions _are_ affected by the '--auto' flag, which generates +auto postings, which can alter account balances. Because auto postings +are optional in hledger, accounts affected by them effectively have two +balances. But balance assertions can only test one or the other of +these. So to avoid making fragile assertions, either: + + * assert the balance calculated with '--auto', and always use + '--auto' with that file + * or assert the balance calculated without '--auto', and never use + '--auto' with that file + * or avoid balance assertions on accounts affected by auto postings + (or avoid auto postings entirely). + + +File: hledger.info, Node: Assertions and precision, Next: Assertions and hledger add, Prev: Assertions and auto postings, Up: Balance assertions + +8.12.9 Assertions and precision +------------------------------- + +Balance assertions compare the exactly calculated amounts, which are not +always what is shown by reports. Eg a commodity directive may limit the +display precision, but this will not affect balance assertions. Balance +assertion failure messages show exact amounts. + + +File: hledger.info, Node: Assertions and hledger add, Prev: Assertions and precision, Up: Balance assertions + +8.12.10 Assertions and hledger add +---------------------------------- + +Balance assertions can be included in the amounts given in 'add'. All +types of assertions are supported, and assertions can be used as in a +normal journal file. + + All transactions, not just those that have an explicit assertion, are +validated against the existing assertions in the journal. This means it +is possible for an added transaction to fail even if its assertions are +correct as of the transaction date. + + If this assertion checking is not desired, then it can be disabled +with '-I'. + + However, balance assignments are currently not supported. + + +File: hledger.info, Node: Posting comments, Next: Transaction balancing, Prev: Balance assertions, Up: Journal + +8.13 Posting comments +===================== + +Text following ';', at the end of a posting line, and/or on indented +lines immediately below it, form comments for that posting. They are +reproduced by 'print' but otherwise ignored, except they may contain +tags, which are not ignored. + +2012-01-01 + expenses 1 ; a comment for posting 1 + assets + ; a comment for posting 2 + ; a second comment line for posting 2 + + +File: hledger.info, Node: Transaction balancing, Next: Tags, Prev: Posting comments, Up: Journal + +8.14 Transaction balancing +========================== + +How exactly does hledger decide when a transaction is balanced ? +Especially when it involves costs, which often are not exact, because of +repeating decimals, or imperfect data from financial institutions ? In +each commodity, hledger sums the transaction's posting amounts, after +converting any with costs; then it checks if that sum is zero, when +rounded to a suitable number of decimal digits - which we call the +_balancing precision_. + + Since version 1.50, hledger infers balancing precision in each +transaction from the amounts in that transaction's journal entry (like +Ledger). Ie, when checking the balance of commodity A, it uses the +highest decimal precision seen for A in the journal entry (excluding +cost amounts). This makes transaction balancing robust; any imbalances +must be visibly accounted for in the journal entry, display precision +can be freely increased with '-c', and compatibility with Ledger and +Beancount journals is good. + + Note that hledger versions before 1.50 worked differently: they +allowed display precision to override the balancing precision. This +masked small imbalances and caused fragility (see issue #2402). As a +result, some journal entries (or CSV rules) that worked with hledger +<1.50, are now rejected with an "unbalanced transaction" error. If you +hit this problem, it's easy to fix: + + * You can restore the old behaviour, by adding '--txn-balancing=old' + to the command or to your '~/.hledger.conf' file. This lets you + keep using old journals unchanged, though without the above + benefits. + + * Or you can fix the problem entries (recommended). There are three + ways, use whichever seems best: + + 1. make cost amounts more precise (add more/better decimal + digits) + 2. or make non-cost amounts less precise (remove unnecessary + decimal digits that are raising the precision) + 3. or add a posting to absorb the imbalance (eg + "expenses:rounding". Remember that one posting may omit the + amount; that's convenient here.) + + +File: hledger.info, Node: Tags, Next: Directives, Prev: Transaction balancing, Up: Journal + +8.15 Tags +========= + +Tags are a way to add extra labels or data fields to transactions, +postings, or accounts. They are usually a word or hyphenated word, +immediately followed by a full colon, written within the comment of a +transaction, a posting, or an 'account' directive. (Yes, storing data +in comments is slightly weird!) + + You can write each tag on its own comment line, or multiple tags on +one line, separated by commas. Tags can also have a value, which is any +text after the colon until the next comma or end of line, excluding +surrounding whitespace. (hledger tag values can't contain commas.) If +the same tag name appears multiple times in a comment, each name:value +pair is preserved. + + An example: in this journal there are six tags, one of them with a +value: + +account assets:checking ; accounttag: +account expenses:food + +2017/1/16 bought groceries ; transactiontag: + ; transactiontag2: + assets:checking $-1 + ; posting-tag-1:, (belongs to the posting above) + expenses:food $1 ; posting-tag-2:, posting-tag-3: with a value + +* Menu: + +* Querying with tags:: +* Displaying tags:: +* When to use tags ?:: +* Tag names:: +* Special tags:: + + +File: hledger.info, Node: Querying with tags, Next: Displaying tags, Up: Tags + +8.15.1 Querying with tags +------------------------- + +Tags are most often used to select a subset of data; you can match +tagged things by tag name and or tag value with a 'tag:' query. (See +queries below.) + + When querying for tag names or values, note that postings inherit +tags from their transaction and from their account, and transactions +acquire tags from their postings. So in the example above, - the +assets:checking posting effectively has four tags (one of its own, one +from the account, two from the transaction) - the expenses:food posting +effectively has four tags (two of its own, two from the transaction) - +the transaction effectively has all six tags (two of its own, and two +from each posting) + + +File: hledger.info, Node: Displaying tags, Next: When to use tags ?, Prev: Querying with tags, Up: Tags + +8.15.2 Displaying tags +---------------------- + +You can use the 'tags' command to list tag names or values. + + The 'print' command also shows tags. + + You can use -pivot to display tag values in other reports, in various +ways (eg appended to account names, like pseudo subaccounts). + + +File: hledger.info, Node: When to use tags ?, Next: Tag names, Prev: Displaying tags, Up: Tags + +8.15.3 When to use tags ? +------------------------- + +Tags provide more dimensions of categorisation, complementing accounts +and transaction descriptions. When to use each of these is somewhat a +matter of taste. Accounts have the most built-in support, and regex +queries on descriptions are also quite powerful. So you may not need +tags at all. But if you want to track multiple cross-cutting +categories, they can be a good fit. For example, you could tag +trip-related transactions with 'trip: YEAR:PLACE', without disturbing +your usual account categories. + + +File: hledger.info, Node: Tag names, Next: Special tags, Prev: When to use tags ?, Up: Tags + +8.15.4 Tag names +---------------- + +What is allowed in a tag name ? Currently, most non-whitespace +characters. Eg '😀:' is a valid tag. + + For extra error checking, you can declare valid tag names with the +'tag' directive, and then enforce these with the 'check' command. + + But note that tags are detected quite loosely at present, sometimes +where you didn't intend them. Eg '; see https://foo.com' contains a +'https' tag with value '//foo.com'. + + +File: hledger.info, Node: Special tags, Prev: Tag names, Up: Tags + +8.15.5 Special tags +------------------- + +Some tag names have special significance to hledger. They are explained +elsewhere, but here's a quick reference: + + type -- declares an account's type + date -- overrides a posting's date + date2 -- overrides a posting's secondary date + assert -- appears on txns generated by close --assert + retain -- appears on txns generated by close --retain + start -- appears on txns generated by close --migrate/--close/--open/--assign + t -- appears on postings generated from timedot letters + + generated-transaction -- appears on txns generated by a periodic rule + modified-transaction -- appears on txns which have had auto postings added + generated-posting -- appears on generated postings + cost-posting -- appears on postings which have (or could have) a cost, + and which have equivalent conversion postings in the transaction + conversion-posting -- appears on postings which are to a V/Conversion account + and which have an equivalent cost posting in the transaction + + The second group above (generated-transaction, etc.) are normally +hidden, with a '_' prefix added. This means 'print' doesn't show them +by default; but you can still use them in queries. You can add the +'--verbose-tags' flag to make them visible, which can be useful for +troubleshooting. + + +File: hledger.info, Node: Directives, Next: account directive, Prev: Tags, Up: Journal + +8.16 Directives +=============== + +Besides transactions, there is something else you can put in a 'journal' +file: directives. These are declarations, beginning with a keyword, +that modify hledger's behaviour. Some directives can have more specific +subdirectives, indented below them. hledger's directives are similar to +Ledger's in many cases, but there are also many differences. Directives +are not required, but can be useful. Here are the main directives: + +purpose directive +-------------------------------------------------------------------------- +*READING DATA:* +Rewrite account names 'alias' +Comment out sections of the file 'comment' +Declare file's decimal mark, to help 'decimal-mark' +parse amounts accurately +Include other data files 'include' +*GENERATING DATA:* +Generate recurring transactions or '~' +budget goals +Generate extra postings on existing '=' +transactions +*CHECKING FOR ERRORS:* +Define valid entities to provide more 'account', 'commodity', +error checking 'payee', 'tag' +*REPORTING:* +Declare accounts' type and display 'account' +order +Declare commodity display styles 'commodity' +Declare market prices 'P' + +* Menu: + +* Directives and multiple files:: +* Directive effects:: + + +File: hledger.info, Node: Directives and multiple files, Next: Directive effects, Up: Directives + +8.16.1 Directives and multiple files +------------------------------------ + +Directives vary in their scope, ie which journal entries and which input +files they affect. Most often, a directive will affect the following +entries and included files if any, until the end of the current file - +and no further. You might find this inconvenient! For example, 'alias' +directives do not affect parent or sibling files. But there are usually +workarounds; for example, put 'alias' directives in your top-most file, +before including other files. + + The restriction, though it may be annoying at first, is in a good +cause; it allows reports to be stable and deterministic, independent of +the order of input. Without it, reports could show different numbers +depending on the order of -f options, or the positions of include +directives in your files. + + +File: hledger.info, Node: Directive effects, Prev: Directives and multiple files, Up: Directives + +8.16.2 Directive effects +------------------------ + +Here are all hledger's directives, with their effects and scope +summarised - nine main directives, plus four others which we consider +non-essential: + +directivewhat it does ends + at + file + end? +--------------------------------------------------------------------------- +*'account'*Declares an account, for checking all entries in all files; andN + its display order and type. Subdirectives: any text, ignored. +*'alias'*Rewrites account names, in following entries until end of Y + current file or 'end aliases'. Command line equivalent: + '--alias' +*'comment'*Ignores part of the journal file, until end of current file orY + 'end comment'. +*'commodity'*Declares up to four things: 1. a commodity symbol, for checkingN,N,Y,Y + all amounts in all files 2. the display style for all amounts + of this commodity 3. the decimal mark for parsing amounts of + this commodity, in the rest of this file and its children, if + there is no 'decimal-mark' directive 4. the precision to use + for balanced-transaction checking in this commodity, in this + file and its children. Takes precedence over 'D'. + Subdirectives: 'format' (ignored). Command line equivalent: + '-c/--commodity-style' +*'decimal-mark'*Declares the decimal mark, for parsing amounts of all Y + commodities in following entries until next 'decimal-mark' or + end of current file. Included files can override. Takes + precedence over 'commodity' and 'D'. +*'include'*Includes entries and directives from another file, as if theyN + were written inline. Command line alternative: multiple + '-f/--file' +*'payee'*Declares a payee name, for checking all entries in all files. N +*'P'*Declares the market price of a commodity on some date, for value N + reports. +*'~'*Declares a periodic transaction rule that generates future N +(tilde)transactions with '--forecast' and budget goals with 'balance + --budget'. +Other +syntax: +*'applyPrepends a common parent account to all account names, in Y +account'*following entries until end of current file or 'end apply + account'. +*'D'*Sets a default commodity to use for no-symbol amounts;and, if Y,Y,N,N + there is no 'commodity' directive for this commodity: its + decimal mark, balancing precision, and display style, as above. +*'Y'*Sets a default year to use for any yearless dates, in following Y + entries until end of current file. +*'='*Declares an auto posting rule that generates extra postings on partly +(equals)matched transactions with '--auto', in current, parent, and + child files (but not sibling files, see #1212). +*OtherOther directives from Ledger's file format are accepted but +Ledgerignored. +directives* + + +File: hledger.info, Node: account directive, Next: alias directive, Prev: Directives, Up: Journal + +8.17 'account' directive +======================== + +'account' directives can be used to declare accounts (ie, the places +that amounts are transferred from and to). Though not required, these +declarations can provide several benefits: + + * They can document your intended chart of accounts, providing a + reference. + * They can store additional account information as comments, or as + tags which can be used to filter or pivot reports. + * They can restrict which accounts may be posted to by transactions, + eg in strict mode, which helps prevent errors. + * They influence account display order in reports, allowing + non-alphabetic sorting (eg Revenues to appear above Expenses). + * They can help hledger know your accounts' types (asset, liability, + equity, revenue, expense), enabling reports like balancesheet and + incomestatement. + * They help with account name completion (in hledger add, + hledger-web, hledger-iadd, ledger-mode, etc.) + + They are written as the word 'account' followed by a hledger-style +account name. Eg: + +account assets:bank:checking + + Ledger-style indented subdirectives are also accepted, but ignored: + +account assets:bank:checking + format subdirective ; currently ignored + +* Menu: + +* Account comments:: +* Account error checking:: +* Account display order:: +* Account types:: + + +File: hledger.info, Node: Account comments, Next: Account error checking, Up: account directive + +8.17.1 Account comments +----------------------- + +Text following *two or more spaces* and ';' at the end of an account +directive line, and/or following ';' on indented lines immediately below +it, form comments for that account. They are ignored except they may +contain tags, which are not ignored. + + The two-space requirement for same-line account comments is because +';' is allowed in account names. + +account assets:bank:checking ; same-line comment, at least 2 spaces before the semicolon + ; next-line comment + ; some tags - type:A, acctnum:12345 + + +File: hledger.info, Node: Account error checking, Next: Account display order, Prev: Account comments, Up: account directive + +8.17.2 Account error checking +----------------------------- + +By default, accounts need not be declared; they come into existence when +a posting references them. This is convenient, but it means hledger +can't warn you when you mis-spell an account name in the journal. +Usually you'll find that error later, as an extra account in balance +reports, or an incorrect balance when reconciling. + + In strict mode, enabled with the '-s'/'--strict' flag, or when you +run 'hledger check accounts', hledger will report an error if any +transaction uses an account name that has not been declared by an +account directive. Some notes: + + * The declaration is case-sensitive; transactions must use the + correct account name capitalisation. + * The account directive's scope is "whole file and below" (see + directives). This means it affects all of the current file, and + any files it includes, but not parent or sibling files. The + position of account directives within the file does not matter, + though it's usual to put them at the top. + * Accounts can only be declared in 'journal' files, but will affect + included files of all types. + * It's currently not possible to declare "all possible subaccounts" + with a wildcard; every account posted to must be declared. + * If you use the -infer-equity flag, you will also need declarations + for the account names it generates. + + +File: hledger.info, Node: Account display order, Next: Account types, Prev: Account error checking, Up: account directive + +8.17.3 Account display order +---------------------------- + +Account directives also cause hledger to display accounts in a +particular order, not just alphabetically. Eg, here is a conventional +ordering for the top-level accounts: + +account assets +account liabilities +account equity +account revenues +account expenses + + Now hledger displays them in that order: + +$ hledger accounts +assets +liabilities +equity +revenues +expenses + + If there are undeclared accounts, those will be displayed last, in +alphabetical order. + + Sorting is done within each group of sibling accounts, at each level +of the account tree. Eg, a declaration like 'account parent:child' +influences 'child''s position among its siblings. + + Note, it does not affect 'parent''s position; for that, you need an +'account parent' declaration. + + Sibling accounts are always displayed together; hledger won't display +'x:y' in between 'a:b' and 'a:c'. + + An account directive both declares an account as a valid posting +target, and declares its display order; you can't easily do one without +the other. + + +File: hledger.info, Node: Account types, Prev: Account display order, Up: account directive + +8.17.4 Account types +-------------------- + +hledger knows that in accounting there are three main account types: + +'Asset' 'A' things you own +'Liability' 'L' things you owe +'Equity' 'E' owner's investment, balances the two above + + and two more representing changes in these: + +'Revenue' 'R' inflows (also known as 'Income') +'Expense' 'X' outflows + + hledger also uses a couple of subtypes: + +'Cash' 'C' liquid assets +'Conversion' 'V' commodity conversions equity + + As a convenience, hledger will detect these types automatically from +english account names. But it's better to declare them explicitly by +adding a 'type:' tag in the account directives. The tag's value can be +any of the types or one-letter abbreviations above. + + Here is a typical set of account type declarations. Subaccounts will +inherit their parent's type, or can override it: + +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 + + This enables the easy balancesheet, balancesheetequity, cashflow and +incomestatement reports, and querying by type:. + + Tips: + + * You can list accounts and their types, for troubleshooting: + + $ hledger accounts --types [ACCTPAT] [type:TYPECODES] [-DEPTH] [--positions] + + * It's a good idea to declare at least one account for each account + type. Having some types declared and some inferred can disrupt + certain reports. + + * The rules for inferring types from account names are as follows + (using Regular expressions). + If they don't work for you, just ignore them and declare your types + with 'type:' tags. + + If account's name contains this case insensitive 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 + + * As mentioned above, subaccounts will inherit a type from their + parent account. To be precise, an account's type is decided by the + first of these that exists: + + 1. A 'type:' declaration for this account. + 2. A 'type:' declaration in the parent accounts above it, + preferring the nearest. + 3. An account type inferred from this account's name. + 4. An account type inferred from a parent account's name, + preferring the nearest parent. + 5. Otherwise, it will have no type. + + * Account aliases can disrupt account types. + + +File: hledger.info, Node: alias directive, Next: commodity directive, Prev: account directive, Up: Journal + +8.18 'alias' directive +====================== + +You can define account alias rules which rewrite your account names, or +parts of them, before generating reports. This can be useful for: + + * expanding shorthand account names to their full form, allowing + easier data entry and a less verbose journal + * adapting old journals to your current chart of accounts + * experimenting with new account organisations, like a new hierarchy + * combining two accounts into one, eg to see their sum or difference + on one line + * customising reports + + Account aliases also rewrite account names in account directives. +They do not affect account names being entered via hledger add or +hledger-web. + + Account aliases are very powerful. They are generally easy to use +correctly, but you can also generate invalid account names with them; +more on this below. + + See also Rewrite account names. + +* Menu: + +* Basic aliases:: +* Regex aliases:: +* Combining aliases:: +* Aliases and multiple files:: +* end aliases directive:: +* Aliases can generate bad account names:: +* Aliases and account types:: + + +File: hledger.info, Node: Basic aliases, Next: Regex aliases, Up: alias directive + +8.18.1 Basic aliases +-------------------- + +To set an account alias, use the 'alias' directive in your journal file. +This affects all subsequent journal entries in the current file or its +included files (but note: not sibling or parent files). The spaces +around the = are optional: + +alias OLD = NEW + + Or, you can use the '--alias 'OLD=NEW'' option on the command line. +This affects all entries. It's useful for trying out aliases +interactively. + + OLD and NEW are case sensitive full account names. hledger will +replace any occurrence of the old account name with the new one. +Subaccounts are also affected. Eg: + +alias checking = assets:bank:wells fargo:checking +; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" + + +File: hledger.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: alias directive + +8.18.2 Regex aliases +-------------------- + +There is also a more powerful variant that uses a regular expression, +indicated by wrapping the pattern in forward slashes. (This is the only +place where hledger requires forward slashes around a regular +expression.) + + Eg: + +alias /REGEX/ = REPLACEMENT + + or: + +$ hledger --alias '/REGEX/=REPLACEMENT' ... + + Any part of an account name matched by REGEX will be replaced by +REPLACEMENT. REGEX is case-insensitive as usual. + + If you need to match a forward slash, escape it with a backslash, eg +'/\/=:'. + + If REGEX contains parenthesised match groups, these can be referenced +by the usual backslash and number in REPLACEMENT: + +alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3 +; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" + + REPLACEMENT continues to the end of line (or on command line, to end +of option argument), so it can contain trailing whitespace. + + +File: hledger.info, Node: Combining aliases, Next: Aliases and multiple files, Prev: Regex aliases, Up: alias directive + +8.18.3 Combining aliases +------------------------ + +You can define as many aliases as you like, using journal directives +and/or command line options. + + Recursive aliases - where an account name is rewritten by one alias, +then by another alias, and so on - are allowed. Each alias sees the +effect of previously applied aliases. + + In such cases it can be important to understand which aliases will be +applied and in which order. For (each account name in) each journal +entry, we apply: + + 1. 'alias' directives preceding the journal entry, most recently + parsed first (ie, reading upward from the journal entry, bottom to + top) + 2. '--alias' options, in the order they appeared on the command line + (left to right). + + In other words, for (an account name in) a given journal entry: + + * the nearest alias declaration before/above the entry is applied + first + * the next alias before/above that will be be applied next, and so on + * aliases defined after/below the entry do not affect it. + + This gives nearby aliases precedence over distant ones, and helps +provide semantic stability - aliases will keep working the same way +independent of which files are being read and in which order. + + In case of trouble, adding '--debug=6' to the command line will show +which aliases are being applied when. + + +File: hledger.info, Node: Aliases and multiple files, Next: end aliases directive, Prev: Combining aliases, Up: alias directive + +8.18.4 Aliases and multiple files +--------------------------------- + +As explained at Directives and multiple files, 'alias' directives do not +affect parent or sibling files. Eg in this command, + +hledger -f a.aliases -f b.journal + + account aliases defined in a.aliases will not affect b.journal. +Including the aliases doesn't work either: + +include a.aliases + +2023-01-01 ; not affected by a.aliases + foo 1 + bar + + This means that account aliases should usually be declared at the +start of your top-most file, like this: + +alias foo=Foo +alias bar=Bar + +2023-01-01 ; affected by aliases above + foo 1 + bar + +include c.journal ; also affected + + +File: hledger.info, Node: end aliases directive, Next: Aliases can generate bad account names, Prev: Aliases and multiple files, Up: alias directive + +8.18.5 'end aliases' directive +------------------------------ + +You can clear (forget) all currently defined aliases (seen in the +journal so far, or defined on the command line) with this directive: + +end aliases + + +File: hledger.info, Node: Aliases can generate bad account names, Next: Aliases and account types, Prev: end aliases directive, Up: alias directive + +8.18.6 Aliases can generate bad account names +--------------------------------------------- + +Be aware that account aliases can produce malformed account names, which +could cause confusing reports or invalid 'print' output. For example, +you could erase all account names: + +2021-01-01 + a:aa 1 + b + +$ hledger print --alias '/.*/=' +2021-01-01 + 1 + + The above 'print' output is not a valid journal. Or you could insert +an illegal double space, causing 'print' output that would give a +different journal when reparsed: + +2021-01-01 + old 1 + other + +$ hledger print --alias old="new USD" | hledger -f- print +2021-01-01 + new USD 1 + other + + +File: hledger.info, Node: Aliases and account types, Prev: Aliases can generate bad account names, Up: alias directive + +8.18.7 Aliases and account types +-------------------------------- + +If an account with a type declaration (see Declaring accounts > Account +types) is renamed by an alias, normally the account type remains in +effect. + + However, renaming in a way that reshapes the account tree (eg +renaming parent accounts but not their children, or vice versa) could +prevent child accounts from inheriting the account type of their +parents. + + Secondly, if an account's type is being inferred from its name, +renaming it by an alias could prevent or alter that. + + If you are using account aliases and the 'type:' query is not +matching accounts as you expect, try troubleshooting with the accounts +command, eg something like: + +$ hledger accounts --types -1 --alias assets=bassetts + + +File: hledger.info, Node: commodity directive, Next: decimal-mark directive, Prev: alias directive, Up: Journal + +8.19 'commodity' directive +========================== + +The 'commodity' directive performs several functions: + + 1. It declares which commodity symbols may be used in the journal, + enabling useful error checking with strict mode or the check + command. See Commodity error checking below. + + 2. It declares how all amounts in this commodity should be displayed, + eg how many decimals to show. See Commodity display style above. + + 3. (If no 'decimal-mark' directive is in effect:) It sets the decimal + mark to expect (period or comma) when parsing amounts in this + commodity, in this file and files it includes, from the directive + until end of current file. See Decimal marks above. + + 4. It declares the precision with which this commodity's amounts + should be compared when checking for balanced transactions, + anywhere in this file and files it includes, until end of current + file. + + Declaring commodities solves several common parsing/display problems, +so we recommend it. + + Note that effects 3 and 4 above end at the end of the directive's +file, and will not affect sibling or parent files. So if you are +relying on them (especially 4) and using multiple files, placing your +commodity directives in a top-level parent file might be important. Or, +keep your decimal marks unambiguous and your entries well balanced and +precise. + + (Related: #793) + +* Menu: + +* Commodity directive syntax:: +* Commodity error checking:: + + +File: hledger.info, Node: Commodity directive syntax, Next: Commodity error checking, Up: commodity directive + +8.19.1 Commodity directive syntax +--------------------------------- + +A commodity directive is normally the word 'commodity' followed by a +sample amount (and optionally a comment). Only the amount's symbol and +the number's format is significant. Eg: + +commodity $1000.00 +commodity 1.000,00 EUR +commodity 1 000 000.0000 ; the no-symbol commodity + + Commodities do not have tags (tags in the comment will be ignored). + + A commodity directive's sample amount must always include a period or +comma decimal mark (this rule helps disambiguate decimal marks and digit +group marks). If you don't want to show any decimal digits, write the +decimal mark at the end: + +commodity 1000. AAAA ; show AAAA with no decimals + + Commodity symbols containing spaces, numbers, or punctuation must be +enclosed in double quotes, as usual: + +commodity 1.0000 "AAAA 2023" + + Commodity directives normally include a sample amount, but can +declare only a symbol (ie, just function 1 above): + +commodity $ +commodity INR +commodity "AAAA 2023" +commodity "" ; the no-symbol commodity + + Commodity directives may also be written with an indented 'format' +subdirective, as in Ledger. The symbol is repeated and must be the same +in both places. Other subdirectives are currently ignored: + +; display indian rupees with currency name on the left, +; thousands, lakhs and crores comma-separated, +; period as decimal point, and two decimal places. +commodity INR + format INR 1,00,00,000.00 + an unsupported subdirective ; ignored by hledger + + +File: hledger.info, Node: Commodity error checking, Prev: Commodity directive syntax, Up: commodity directive + +8.19.2 Commodity error checking +------------------------------- + +In strict mode ('-s'/'--strict') (or when you run 'hledger check +commodities'), hledger will report an error if an undeclared commodity +symbol is used. (With one exception: zero amounts are always allowed to +have no commodity symbol.) It works like account error checking +(described above). + + +File: hledger.info, Node: decimal-mark directive, Next: include directive, Prev: commodity directive, Up: Journal + +8.20 'decimal-mark' directive +============================= + +You can use a 'decimal-mark' directive - usually one per file, at the +top of the file - to declare which character represents a decimal mark +when parsing amounts in this file. It can look like + +decimal-mark . + + or + +decimal-mark , + + This prevents any ambiguity when parsing numbers in the file, so we +recommend it, especially if the file contains digit group marks (eg +thousands separators). + + +File: hledger.info, Node: include directive, Next: P directive, Prev: decimal-mark directive, Up: Journal + +8.21 'include' directive +======================== + +You can pull in the content of additional files by writing an include +directive, like this: + +include SOMEFILE + + This has the same effect as if SOMEFILE's content was inlined at this +point. (With any include directives in SOMEFILE processed similarly, +recursively.) + + Only journal files can include other files. They can include +journal, timeclock or timedot files, but not CSV files. + + If the file path begins with a tilde, that means your home directory: +'include ~/main.journal'. + + If it begins with a slash, it is an absolute path: 'include +/home/user/main.journal'. Otherwise it is relative to the including +file's folder: 'include ../finances/main.journal'. + + Also, the path may have a file type prefix to force a specific file +format, overriding the file extension(s) (as described in Data formats): +'include timedot:notes/2023.md'. + + The path may contain glob patterns to match multiple files. +hledger's globs are similar to zsh's: '?' to match any character; +'[a-z]' to match any character in a range; '*' to match zero or more +characters that aren't a path separator (like '/'); '**' to match zero +or more subdirectories and/or zero or more characters at the start of a +file name; etc. Also, hledger's globs always exclude the including file +itself. So, you can do + + * 'include *.journal' to include all other journal files in the + current directory (excluding dot files) + * 'include **.journal' to include all other journal files in this + directory and below (excluding dot directories/files) + * 'include timelogs/2???.timedot' to include all timedot files named + like a year number. + + There is a limitation: hledger's globs always exclude paths involving +dot files or dot directories. This is a workaround for unavoidable dot +directory traversal; you can disable it and revert to older behaviour +with the '--old-glob' flag, for now. + + If you are using many, or deeply nested, include files, and have an +error that's hard to pinpoint: a good troubleshooting command is +'hledger files --debug=6' (or 7). + + +File: hledger.info, Node: P directive, Next: payee directive, Prev: include directive, Up: Journal + +8.22 'P' directive +================== + +The 'P' directive declares a market price, which is a conversion rate +between two commodities on a certain date. This allows value reports to +convert amounts of one commodity to their value in another, on or after +that date. These prices are often obtained from a stock exchange, +cryptocurrency exchange, the or foreign exchange market. + + The format is: + +P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT + + DATE is a simple date, COMMODITY1SYMBOL is the symbol of the +commodity being priced, and COMMODITY2AMOUNT is the amount (symbol and +quantity) of commodity 2 that one unit of commodity 1 is worth on this +date. Examples: + +# one euro was worth $1.35 from 2009-01-01 onward: +P 2009-01-01 € $1.35 + +# and $1.40 from 2010-01-01 onward: +P 2010-01-01 € $1.40 + + The '-V', '-X' and '--value' flags use these market prices to show +amount values in another commodity. See Value reporting. + + +File: hledger.info, Node: payee directive, Next: tag directive, Prev: P directive, Up: Journal + +8.23 'payee' directive +====================== + +'payee PAYEE NAME' + + This directive can be used to declare a limited set of payees which +may appear in transaction descriptions. The "payees" check will report +an error if any transaction refers to a payee that has not been +declared. Eg: + +payee Whole Foods ; a comment + + Payees do not have tags (tags in the comment will be ignored). + + To declare the empty payee name, use '""'. + +payee "" + + Ledger-style indented subdirectives, if any, are currently ignored. + + +File: hledger.info, Node: tag directive, Next: Periodic transactions, Prev: payee directive, Up: Journal + +8.24 'tag' directive +==================== + +'tag TAGNAME' + + This directive can be used to declare a limited set of tag names +allowed in tags. TAGNAME should be a valid tag name (no spaces). Eg: + +tag item-id + + Any indented subdirectives are currently ignored. + + The "tags" check will report an error if any undeclared tag name is +used. It is quite easy to accidentally create a tag through normal use +of colons in comments; if you want to prevent this, you can declare and +check your tags . + + +File: hledger.info, Node: Periodic transactions, Next: Auto postings, Prev: tag directive, Up: Journal + +8.25 Periodic transactions +========================== + +The '~' directive declares a "periodic rule" which generates temporary +extra transactions, usually recurring at some interval, when hledger is +run with the '--forecast' flag. These "forecast transactions" are +useful for forecasting future activity. They exist only for the +duration of the report, and only when '--forecast' is used; they are not +saved in the journal file by hledger. + + Periodic rules also have a second use: with the '--budget' flag they +set budget goals for budgeting. + + Periodic rules can be a little tricky, so before you use them, read +this whole section, or at least the following tips: + + 1. Two spaces accidentally added or omitted will cause you trouble - + read about this below. + 2. For troubleshooting, show the generated transactions with 'hledger + print --forecast tag:generated' or 'hledger register --forecast + tag:generated'. + 3. Forecasted transactions will begin only after the last + non-forecasted transaction's date. + 4. Forecasted transactions will end 6 months from today, by default. + See below for the exact start/end rules. + 5. period expressions can be tricky. Their documentation needs + improvement, but is worth studying. + 6. Some period expressions with a repeating interval must begin on a + natural boundary of that interval. Eg in 'weekly from DATE', DATE + must be a monday. '~ weekly from 2019/10/1' (a tuesday) will give + an error. + 7. Other period expressions with an interval are automatically + expanded to cover a whole number of that interval. (This is done + to improve reports, but it also affects periodic transactions. + Yes, it's a bit inconsistent with the above.) Eg: '~ every 10th + day of month from 2023/01', which is equivalent to '~ every 10th + day of month from 2023/01/01', will be adjusted to start on + 2019/12/10. + +* Menu: + +* Periodic rule syntax:: +* Periodic rules and relative dates:: +* Two spaces between period expression and description!:: + + +File: hledger.info, Node: Periodic rule syntax, Next: Periodic rules and relative dates, Up: Periodic transactions + +8.25.1 Periodic rule syntax +--------------------------- + +A periodic transaction rule looks like a normal journal entry, with the +date replaced by a tilde ('~') followed by a period expression +(mnemonic: '~' looks like a recurring sine wave.): + +# every first of month +~ monthly + expenses:rent $2000 + assets:bank:checking + +# every 15th of month in 2023's first quarter: +~ monthly from 2023-04-15 to 2023-06-16 + expenses:utilities $400 + assets:bank:checking + + The period expression is the same syntax used for specifying +multi-period reports, just interpreted differently; there, it specifies +report periods; here it specifies recurrence dates (the periods' start +dates). + + +File: hledger.info, Node: Periodic rules and relative dates, Next: Two spaces between period expression and description!, Prev: Periodic rule syntax, Up: Periodic transactions + +8.25.2 Periodic rules and relative dates +---------------------------------------- + +Partial or relative dates (like '12/31', '25', 'tomorrow', 'last week', +'next quarter') are usually not recommended in periodic rules, since the +results will change as time passes. If used, they will be interpreted +relative to, in order of preference: + + 1. the first day of the default year specified by a recent 'Y' + directive + 2. or the date specified with '--today' + 3. or the date on which you are running the report. + + They will not be affected at all by report period or forecast period +dates. + + +File: hledger.info, Node: Two spaces between period expression and description!, Prev: Periodic rules and relative dates, Up: Periodic transactions + +8.25.3 Two spaces between period expression and description! +------------------------------------------------------------ + +If the period expression is followed by a transaction description, these +must be separated by *two or more spaces*. This helps hledger know +where the period expression ends, so that descriptions can not +accidentally alter their meaning, as in this example: + +; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2023" +; || +; vv +~ every 2 months in 2023, we will review + assets:bank:checking $1500 + income:acme inc + + So, + + * Do write two spaces between your period expression and your + transaction description, if any. + * Don't accidentally write two spaces in the middle of your period + expression. + + +File: hledger.info, Node: Auto postings, Next: Other syntax, Prev: Periodic transactions, Up: Journal + +8.26 Auto postings +================== + +The '=' directive declares an "auto posting rule", which adds extra +postings to existing transactions. (Remember, postings are the account +name & amount lines below a transaction's date & description.) + + In the journal, an auto posting rule looks quite like a transaction, +but instead of date and description it has '=' (mnemonic: "match") and a +query, like this: + += QUERY + ACCOUNT AMOUNT + ... + + Queries are just like command line queries; an account name substring +is most common. Query terms containing spaces should be enclosed in +single or double quotes. + + Each '=' rule works like this: when hledger is run with the '--auto' +flag, wherever the QUERY matches a posting in the journal, the rule's +postings are added to that transaction, immediately below the matched +posting. Note these generated postings are temporary, existing only for +the duration of the report, and only when '--auto' is used; they are not +saved in the journal file by hledger. + + The postings can contain the special string '%account' which will be +expanded to the account name of the matched account. + + Generated postings' amounts can depend on the matched posting's +amount. So auto postings can be useful for, eg, adding tax postings +with a standard percentage. AMOUNT can be: + + * a number with no commodity symbol, like '2'. The matched posting's + commodity symbol will be added to this. + + * a normal amount with a commodity symbol, like '$2'. This will be + used as-is. + + * an asterisk followed by a number, like '*2'. This will multiply + the matched posting's amount (and total price, if any) by the + number. + + * an asterisk followed by an amount with commodity symbol, like + '*$2'. This multiplies and also replaces the commodity symbol with + this new one. + + Some examples: + +; every time I buy food, schedule a dollar donation += expenses:food + (liabilities:charity) $-1 + +; when I buy a gift, also deduct that amount from a budget envelope subaccount += expenses:gifts + assets:checking:gifts *-1 + assets:checking *1 + +2017/12/1 + expenses:food $10 + assets:checking + +2017/12/14 + expenses:gifts $20 + assets:checking + +$ hledger print --auto +2017-12-01 + expenses:food $10 + assets:checking + (liabilities:charity) $-1 + +2017-12-14 + expenses:gifts $20 + assets:checking + assets:checking:gifts -$20 + assets:checking $20 + + Note that depending fully on generated data such as this has some +drawbacks - it's less portable, less future-proof, less auditable by +others, and less robust (eg your balance assertions will depend on +whether you use or don't use '--auto'). An alternative is to use auto +postings in "one time" fashion - use them to help build a complex +journal entry, view it with 'hledger print --auto', and then copy that +output into the journal file to make it permanent. + +* Menu: + +* Auto postings and multiple files:: +* Auto postings and dates:: +* Auto postings and transaction balancing / inferred amounts / balance assertions:: +* Auto posting tags:: +* Auto postings on forecast transactions only:: + + +File: hledger.info, Node: Auto postings and multiple files, Next: Auto postings and dates, Up: Auto postings + +8.26.1 Auto postings and multiple files +--------------------------------------- + +An auto posting rule can affect any transaction in the current file, or +in any parent file or child file. Note, currently it will not affect +sibling files (when multiple '-f'/'--file' are used - see #1212). + + +File: hledger.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Prev: Auto postings and multiple files, Up: Auto postings + +8.26.2 Auto postings and dates +------------------------------ + +A posting date (or secondary date) in the matched posting, or (taking +precedence) a posting date in the auto posting rule itself, will also be +used in the generated posting. + + +File: hledger.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Next: Auto posting tags, Prev: Auto postings and dates, Up: Auto postings + +8.26.3 Auto postings and transaction balancing / inferred amounts / +------------------------------------------------------------------- + +balance assertions Currently, auto postings are added: + + * after missing amounts are inferred, and transactions are checked + for balancedness, + * but before balance assertions are checked. + + Note this means that journal entries must be balanced both before and +after auto postings are added. This changed in hledger 1.12+; see #893 +for background. + + This also means that you cannot have more than one auto-posting with +a missing amount applied to a given transaction, as it will be unable to +infer amounts. + + +File: hledger.info, Node: Auto posting tags, Next: Auto postings on forecast transactions only, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings + +8.26.4 Auto posting tags +------------------------ + +Automated postings will have some extra tags: + + * 'generated-posting:= QUERY' - shows this was generated by an auto + posting rule, and the query + * '_generated-posting:= QUERY' - a hidden tag, which does not appear + in hledger's output. This can be used to match postings generated + "just now", rather than generated in the past and saved to the + journal. + + Also, any transaction that has been changed by auto posting rules +will have these tags added: + + * 'modified:' - this transaction was modified + * '_modified:' - a hidden tag not appearing in the comment; this + transaction was modified "just now". + + +File: hledger.info, Node: Auto postings on forecast transactions only, Prev: Auto posting tags, Up: Auto postings + +8.26.5 Auto postings on forecast transactions only +-------------------------------------------------- + +Tip: you can can make auto postings that will apply to forecast +transactions but not recorded transactions, by adding +'tag:_generated-transaction' to their QUERY. This can be useful when +generating new journal entries to be saved in the journal. + + +File: hledger.info, Node: Other syntax, Prev: Auto postings, Up: Journal + +8.27 Other syntax +================= + +hledger journal format supports quite a few other features, mainly to +make interoperating with or converting from Ledger easier. Note some of +the features below are powerful and can be useful in special cases, but +in general, features in this section are considered less important or +even not recommended for most users. Downsides are mentioned to help +you decide if you want to use them. + +* Menu: + +* Balance assignments:: +* Bracketed posting dates:: +* D directive:: +* apply account directive:: +* Y directive:: +* Secondary dates:: +* Star comments:: +* Valuation expressions:: +* Virtual postings:: +* Other Ledger directives:: +* Other cost/lot notations:: + + +File: hledger.info, Node: Balance assignments, Next: Bracketed posting dates, Up: Other syntax + +8.27.1 Balance assignments +-------------------------- + +Ledger-style balance assignments are also supported. These are like +balance assertions, but with no posting amount on the left side of the +equals sign; instead it is calculated automatically so as to satisfy the +assertion. This can be a convenience during data entry, eg when setting +opening balances: + +; starting a new journal, set asset account balances +2016/1/1 opening balances + assets:checking = $409.32 + assets:savings = $735.24 + assets:cash = $42 + equity:opening balances + + or when adjusting a balance to reality: + +; no cash left; update balance, record any untracked spending as a generic expense +2016/1/15 + assets:cash = $0 + expenses:misc + + The calculated amount depends on the account's balance in the +commodity at that point (which depends on the previously-dated postings +of the commodity to that account since the last balance assertion or +assignment). + + Downsides: using balance assignments makes your journal less +explicit; to know the exact amount posted, you have to run hledger or do +the calculations yourself, instead of just reading it. Also balance +assignments' forcing of balances can hide errors. These things make +your financial data less portable, less future-proof, and less +trustworthy in an audit. + +* Menu: + +* Balance assignments and costs:: +* Balance assignments and multiple files:: + + +File: hledger.info, Node: Balance assignments and costs, Next: Balance assignments and multiple files, Up: Balance assignments + +8.27.1.1 Balance assignments and costs +...................................... + +A cost in a balance assignment will cause the calculated amount to have +that cost attached: + +2019/1/1 + (a) = $1 @ €2 + +$ hledger print --explicit +2019-01-01 + (a) $1 @ €2 = $1 @ €2 + + +File: hledger.info, Node: Balance assignments and multiple files, Prev: Balance assignments and costs, Up: Balance assignments + +8.27.1.2 Balance assignments and multiple files +............................................... + +Balance assignments handle multiple files like balance assertions. They +see balance from other files previously included from the current file, +but not from previous sibling or parent files. + + +File: hledger.info, Node: Bracketed posting dates, Next: D directive, Prev: Balance assignments, Up: Other syntax + +8.27.2 Bracketed posting dates +------------------------------ + +For setting posting dates and secondary posting dates, Ledger's +bracketed date syntax is also supported: '[DATE]', '[DATE=DATE2]' or +'[=DATE2]' in posting comments. hledger will attempt to parse any +square-bracketed sequence of the '0123456789/-.=' characters in this +way. With this syntax, DATE infers its year from the transaction and +DATE2 infers its year from DATE. + + Downsides: another syntax to learn, redundant with hledger's +'date:'/'date2:' tags, and confusingly similar to Ledger's lot date +syntax. + + +File: hledger.info, Node: D directive, Next: apply account directive, Prev: Bracketed posting dates, Up: Other syntax + +8.27.3 'D' directive +-------------------- + +'D AMOUNT' + + This directive sets a default commodity, to be used for any +subsequent commodityless amounts (ie, plain numbers) seen while parsing +the journal. This effect lasts until the next 'D' directive, or the end +of the current file. + + For compatibility/historical reasons, 'D' also acts like a +'commodity' directive (setting the commodity's decimal mark for parsing +and display style for output). So its argument is not just a commodity +symbol, but a full amount demonstrating the style. The amount must +include a decimal mark (either period or comma). Eg: + +; commodity-less amounts should be treated as dollars +; (and displayed with the dollar sign on the left, thousands separators and two decimal places) +D $1,000.00 + +1/1 + a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00 + b + + Interactions with other directives: + + For setting a commodity's display style, a 'commodity' directive has +highest priority, then a 'D' directive. + + For detecting a commodity's decimal mark during parsing, +'decimal-mark' has highest priority, then 'commodity', then 'D'. + + For checking commodity symbols with the check command, a 'commodity' +directive is required ('hledger check commodities' ignores 'D' +directives). + + Downsides: omitting commodity symbols makes your financial data less +explicit, less portable, and less trustworthy in an audit. It is +usually an unsustainable shortcut; sooner or later you will want to +track multiple commodities. D is overloaded with functions redundant +with 'commodity' and 'decimal-mark'. And it works differently from +Ledger's 'D'. + + +File: hledger.info, Node: apply account directive, Next: Y directive, Prev: D directive, Up: Other syntax + +8.27.4 'apply account' directive +-------------------------------- + +This directive sets a default parent account, which will be prepended to +all accounts in following entries, until an 'end apply account' +directive or end of current file. Eg: + +apply account home + +2010/1/1 + food $10 + cash + +end apply account + + is equivalent to: + +2010/01/01 + home:food $10 + home:cash $-10 + + 'account' directives are also affected, and so is any 'include'd +content. + + Account names entered via hledger add or hledger-web are not +affected. + + Account aliases, if any, are applied after the parent account is +prepended. + + Downsides: this can make your financial data less explicit, less +portable, and less trustworthy in an audit. + + +File: hledger.info, Node: Y directive, Next: Secondary dates, Prev: apply account directive, Up: Other syntax + +8.27.5 'Y' directive +-------------------- + +'Y YEAR' + + or (deprecated backward-compatible forms): + + 'year YEAR' 'apply year YEAR' + + The space is optional. This sets a default year to be used for +subsequent dates which don't specify a year. Eg: + +Y2009 ; set default year to 2009 + +12/15 ; equivalent to 2009/12/15 + expenses 1 + assets + +year 2010 ; change default year to 2010 + +2009/1/30 ; specifies the year, not affected + expenses 1 + assets + +1/31 ; equivalent to 2010/1/31 + expenses 1 + assets + + Downsides: omitting the year (from primary transaction dates, at +least) makes your financial data less explicit, less portable, and less +trustworthy in an audit. Such dates can get separated from their +corresponding Y directive, eg when evaluating a region of the journal in +your editor. A missing Y directive makes reports dependent on today's +date. + + +File: hledger.info, Node: Secondary dates, Next: Star comments, Prev: Y directive, Up: Other syntax + +8.27.6 Secondary dates +---------------------- + +A secondary date is written after the primary date, following an equals +sign: 'DATE1=DATE2'. If the year is omitted, the primary date's year is +assumed. When running reports, the primary (left side) date is used by +default, but with the '--date2' flag ('--aux-date' or'--effective' also +work, for Ledger users), the secondary (right side) date will be used +instead. + + The meaning of secondary dates is up to you. Eg it could be "primary +is the bank's clearing date, secondary is the date the transaction was +initiated, if different". + + In practice, this feature usually adds confusion: + + * You have to remember the primary and secondary dates' meaning, and + follow that consistently. + * It splits your bookkeeping into two modes, and you have to remember + which mode is appropriate for a given report. + * Usually your balance assertions will work with only one of these + modes. + * It makes your financial data more complicated, less portable, and + less clear in an audit. + * It interacts with every feature, creating an ongoing cost for + implementors. + * It distracts new users and supporters. + * Posting dates are simpler and work better. + + So secondary dates are officially deprecated in hledger, remaining +only as a Ledger compatibility aid; we recommend using posting dates +instead. + + +File: hledger.info, Node: Star comments, Next: Valuation expressions, Prev: Secondary dates, Up: Other syntax + +8.27.7 Star comments +-------------------- + +Lines beginning with '*' (star/asterisk) are also comment lines. This +feature allows Emacs users to insert org headings in their journal, +allowing them to fold/unfold/navigate it like an outline when viewed +with org mode. + + Downsides: another, unconventional comment syntax to learn. +Decreases your journal's portability. And switching to Emacs org mode +just for folding/unfolding meant losing the benefits of ledger mode; +nowadays you can add outshine mode to ledger mode to get folding without +losing ledger mode's features. + + +File: hledger.info, Node: Valuation expressions, Next: Virtual postings, Prev: Star comments, Up: Other syntax + +8.27.8 Valuation expressions +---------------------------- + +Ledger allows a valuation function or value to be written in double +parentheses after an amount. hledger ignores these. + + +File: hledger.info, Node: Virtual postings, Next: Other Ledger directives, Prev: Valuation expressions, Up: Other syntax + +8.27.9 Virtual postings +----------------------- + +A posting with parentheses around the account name, like '(some:account) +10', is called an _unbalanced virtual posting_. These postings do not +participate in transaction balancing. (And if you write them without an +amount, a zero amount is always inferred.) These can occasionally be +convenient for special circumstances, but they violate double entry +bookkeeping and make your data less portable across applications, so +many people avoid using them at all. + + A posting with brackets around the account name ('[some:account]') is +called a _balanced virtual posting_. The balanced virtual postings in a +transaction must add up to zero, just like ordinary postings, but +separately from them. These are not part of double entry bookkeeping +either, but they are at least balanced. An example: + +2022-01-01 buy food with cash, update budget envelope subaccounts, & something else + assets:cash $-10 ; <- these balance each other + expenses:food $7 ; <- + expenses:food $3 ; <- + [assets:checking:budget:food] $-10 ; <- and these balance each other + [assets:checking:available] $10 ; <- + (something:else) $5 ; <- this is not required to balance + + Ordinary postings, whose account names are neither parenthesised nor +bracketed, are called _real postings_. You can exclude virtual postings +from reports with the '-R/--real' flag or a 'real:1' query. + + +File: hledger.info, Node: Other Ledger directives, Next: Other cost/lot notations, Prev: Virtual postings, Up: Other syntax + +8.27.10 Other Ledger directives +------------------------------- + +These other Ledger directives are currently accepted but ignored. This +allows hledger to read more Ledger files, but be aware that hledger's +reports may differ from Ledger's if you use these. + +apply fixed COMM AMT +apply tag TAG +assert EXPR +bucket / A ACCT +capture ACCT REGEX +check EXPR +define VAR=EXPR +end apply fixed +end apply tag +end apply year +end tag +eval / expr EXPR +python + PYTHONCODE +tag NAME +value EXPR +--command-line-flags + + See also https://hledger.org/ledger.html for a detailed +hledger/Ledger syntax comparison. + + +File: hledger.info, Node: Other cost/lot notations, Prev: Other Ledger directives, Up: Other syntax + +8.27.11 Other cost/lot notations +-------------------------------- + +A slight digression for Ledger and Beancount users. + + *Ledger* has a number of cost/lot-related notations: + + * '@ UNITCOST' and '@@ TOTALCOST' + * expresses a conversion rate, as in hledger + * when buying, also creates a lot that can be selected at + selling time + + * '(@) UNITCOST' and '(@@) TOTALCOST' (virtual cost) + * like the above, but also means "this cost was exceptional, + don't use it when inferring market prices". + + * '{=UNITCOST}' and '{{=TOTALCOST}}' (fixed price) + * when buying, means "this cost is also the fixed value, don't + let it fluctuate in value reports" + + * '{UNITCOST}' and '{{TOTALCOST}}' (lot price) + * can be used identically to '@ UNITCOST' and '@@ TOTALCOST', + also creates a lot + * when selling, combined with '@ ...', selects an existing lot + by its cost basis. Does not check if that lot is present. + + * '[YYYY/MM/DD]' (lot date) + * when buying, attaches this acquisition date to the lot + * when selling, selects a lot by its acquisition date + + * '(SOME TEXT)' (lot note) + * when buying, attaches this note to the lot + * when selling, selects a lot by its note + + Currently, hledger + + * accepts any or all of the above in any order after the posting + amount + * supports '@' and '@@' + * treats '(@)' and '(@@)' as synonyms for '@' and '@@' + * and ignores the rest. (This can break transaction balancing.) + + *Beancount* has simpler notation and different behaviour: + + * '@ UNITCOST' and '@@ TOTALCOST' + * expresses a cost without creating a lot, as in hledger + * when buying (acquiring) or selling (disposing of) a lot, and + combined with '{...}': is not used except to document the + cost/selling price + + * '{UNITCOST}' and '{{TOTALCOST}}' + * when buying, expresses the cost for transaction balancing, and + also creates a lot with this cost basis attached + * when selling, + * selects a lot by its cost basis + * raises an error if that lot is not present or can not be + selected unambiguously (depending on booking method + configured) + * expresses the selling price for transaction balancing + + * '{}', '{YYYY-MM-DD}', '{"LABEL"}', '{UNITCOST, "LABEL"}', + '{UNITCOST, YYYY-MM-DD, "LABEL"}' + * when selling, other combinations of date/cost/label, like the + above, are accepted for selecting the lot. + + Currently, hledger + + * supports '@' and '@@' + * accepts the '{UNITCOST}'/'{{TOTALCOST}}' notation, but ignores it + * and rejects the rest. + + +File: hledger.info, Node: CSV, Next: Timeclock, Prev: Journal, Up: Top + +9 CSV +***** + +hledger can read transactions from CSV (comma-separated values) files. +More precisely, it can read DSV (delimiter-separated values), from a +file or standard input. Comma-separated, semicolon-separated and +tab-separated are the most common variants, and hledger will recognise +these three automatically based on a '.csv', '.ssv' or '.tsv' file name +extension or a 'csv:', 'ssv:' or 'tsv:' file path prefix. + + (To learn about producing CSV or TSV _output_, see Output format.) + + Each CSV file must be described by a corresponding _rules file_. +This contains rules describing the CSV data (header line, fields layout, +date format etc.), how to construct hledger transactions from it, and +how to categorise transactions based on description or other attributes. + + By default, hledger expects this rules file to be named like the CSV +file, with an extra '.rules' extension added, in the same directory. Eg +when asked to read 'foo/FILE.csv', hledger looks for +'foo/FILE.csv.rules'. You can specify a different rules file with the +'--rules' option. + + At minimum, the rules file must identify the date and amount fields, +and often it also specifies the date format and how many header lines +there are. Here's a simple CSV file and a rules file for it: + +Date, Description, Id, Amount +12/11/2019, Foo, 123, 10.23 + +# basic.csv.rules +skip 1 +fields date, description, , amount +date-format %d/%m/%Y + +$ hledger print -f basic.csv +2019-11-12 Foo + expenses:unknown 10.23 + income:unknown -10.23 + + There's an introductory Tutorial: Import CSV data 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:: +* archive:: +* encoding:: +* separator:: +* skip:: +* date-format:: +* timezone:: +* newest-first:: +* intra-day-reversed:: +* decimal-mark:: +* fields list:: +* Field assignment:: +* Field names:: +* if block:: +* Matchers:: +* if table:: +* balance-type:: +* include:: +* Working with CSV:: +* CSV rules examples:: + + +File: hledger.info, Node: CSV rules cheatsheet, Next: source, Up: CSV + +9.1 CSV rules cheatsheet +======================== + +The following kinds of rule can appear in the rules file, in any order. +(Blank lines and lines beginning with '#' or ';' or '*' are ignored.) + +*'source'* optionally declare which file to read data + from +*'archive'* optionally enable an archive of imported files +*'encoding'* optionally declare which text encoding the + data has +*'separator'* declare the field separator, instead of + relying on file extension +*'decimal-mark'* declare the decimal mark used in CSV amounts, + when ambiguous +*'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 +*'skip'* (at top level) skip header line(s) at start of + file +*'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 +*'skip'* (inside an 'if' rule) skip current record(s) +*'end'* (inside an 'if' rule) skip all remaining + records +*'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: archive, Prev: CSV rules cheatsheet, Up: CSV + +9.2 'source' +============ + +If you tell hledger to read a csv file with '-f foo.csv', it will look +for rules in 'foo.csv.rules'. Or, you can tell it to read the rules +file, with '-f foo.csv.rules', and it will look for data in 'foo.csv' +(since 1.30). These are mostly equivalent, but the second method +provides some extra features. For one, the data file can be missing, +without causing an error; it is just considered empty. + + For more flexibility, add a 'source' rule, which lets you specify a +different data file: + +source ./Checking1.csv + + If the file does not exist, it is just considered empty, without +raising an error. + + If you specify just a file name with no path, hledger will look for +it in the '~/Downloads' folder: + +source Checking1.csv + + You can use a glob pattern, to avoid specifying the file name +exactly: + +source Checking1*.csv + + This has another benefit: if the pattern matches multiple files, +hledger will read the newest (most recently modified) one. This avoids +problems if you have downloaded a file multiple times without cleaning +up. + + All this enables a convenient workflow where can you just download +CSV files, then run 'hledger import rules/*'. + + See also "Working with CSV > Reading files specified by rule". + +* Menu: + +* Data cleaning / data generating commands:: + + +File: hledger.info, Node: Data cleaning / data generating commands, Up: source + +9.2.1 Data cleaning / data generating commands +---------------------------------------------- + +After 'source''s file pattern, you can write '|' (pipe) and a data +cleaning command (or command pipeline). If hledger's CSV rules aren't +enough, you can pre-process the downloaded data here with a shell +command or script, to make it more suitable for conversion. The command +will be executed by your default shell, in the directory of the rules +file, will receive the data file's content as standard input, and should +output zero or more lines of character-separated-values, suitable for +conversion by the CSV rules. + + Examples: + +source ./paypal.json | paypalcsv +source data/simplefin.json | simplefincsv - 'chase.*card' +source OfxDownload*.csv | grep -vE '^(([^,]*,){6}[^,]*|)$' | sort -t, -n +2 +source History_for_Account_Z20144832*.csv # | grep -E '^([^,]*,){12}[^,]*$' | sed -E -e 's/^ //' -e 's/\.([0-9]),/.\10,/g' -e 's/,([0-9]+),/,\1.00,/g' + + Or, after 'source' you can write '|' and a data generating command +(with no file pattern before the '|'). This command receives no input, +and should output zero or more lines of character-separated values, +suitable for conversion by the CSV rules. + + Examples: + +source | paypaljson | paypalcsv +source | paypalcsv data/paypal.json +source | simplefinjson >data/simplefin.json && simplefincsv data/simplefin.json 'chase.*card' +source | simplefincsv data/simplefin.json 'unify.*checking' + + ('paypal*' and 'simplefin*' scripts are in bin/) + + Whenever hledger runs one of these commands, it will echo the command +on stderr. If the command produces error output, but exits +successfully, hledger will show the error output as a warning. If the +command fails, hledger will fail and show the error output in the error +message. + + _Added in 1.50; experimental._ + + +File: hledger.info, Node: archive, Next: encoding, Prev: source, Up: CSV + +9.3 'archive' +============= + +With 'archive' added to a rules file, the 'import' command will archive +each successfully processed data file or data command output in a nearby +'data/' directory. The archive file name will be based on the rules +file and the data file's modification date and extension (or for a +data-generating command, the current date and the ".csv" extension). +The original data file, if any, will be removed. + + Also, in this mode 'import' will prefer the oldest file matched by +the 'source' rule's glob pattern, not the newest. (So if there are +multiple downloads, they will be imported and archived oldest first.) + + Archiving is optional, but it can be useful for troubleshooting your +CSV rules, regenerating entries with improved rules, checking for +variations in your bank's CSV, etc. + + _Added in 1.50; experimental._ + + +File: hledger.info, Node: encoding, Next: separator, Prev: archive, Up: CSV + +9.4 'encoding' +============== + +encoding ENCODING + + hledger normally expects non-ascii text to be using the system +locale's text encoding. If you need to read CSV files which have some +other encoding, you can do it by adding 'encoding ENCODING' to your CSV +rules. Eg: 'encoding iso-8859-1'. + + The following encodings are supported: + + 'ascii', 'utf-8', 'utf-16', 'utf-32', 'iso-8859-1', 'iso-8859-2', +'iso-8859-3', 'iso-8859-4', 'iso-8859-5', 'iso-8859-6', 'iso-8859-7', +'iso-8859-8', 'iso-8859-9', 'iso-8859-10', 'iso-8859-11', 'iso-8859-13', +'iso-8859-14', 'iso-8859-15', 'iso-8859-16', 'cp1250', 'cp1251', +'cp1252', 'cp1253', 'cp1254', 'cp1255', 'cp1256', 'cp1257', 'cp1258', +'koi8-r', 'koi8-u', 'gb18030', 'macintosh', 'jis-x-0201', 'jis-x-0208', +'iso-2022-jp', 'shift-jis', 'cp437', 'cp737', 'cp775', 'cp850', 'cp852', +'cp855', 'cp857', 'cp860', 'cp861', 'cp862', 'cp863', 'cp864', 'cp865', +'cp866', 'cp869', 'cp874', 'cp932'. + + _Added in 1.42._ + + +File: hledger.info, Node: separator, Next: skip, Prev: encoding, Up: CSV + +9.5 'separator' +=============== + +You can use the 'separator' rule to read other kinds of +character-separated data. The argument is any single separator +character, or the words 'tab' or 'space' (case insensitive). Eg, for +comma-separated values (CSV): + +separator , + + or for semicolon-separated values (SSV): + +separator ; + + or for tab-separated values (TSV): + +separator TAB + + If the input file has a '.csv', '.ssv' or '.tsv' file extension (or a +'csv:', 'ssv:', 'tsv:' prefix), the appropriate separator will be +inferred automatically, and you won't need this rule. + + +File: hledger.info, Node: skip, Next: date-format, Prev: separator, Up: CSV + +9.6 'skip' +========== + +skip N + + The word 'skip' followed by a number (or no number, meaning 1) tells +hledger to ignore this many non-empty lines at the start of the input +data. You'll need this whenever your CSV data contains header lines. +Note, empty and blank lines are skipped automatically, so you don't need +to count those. + + 'skip' has a second meaning: it can be used inside if blocks +(described below), to skip one or more records whenever the condition is +true. Records skipped in this way are ignored, except they are still +required to be valid CSV. + + +File: hledger.info, Node: date-format, Next: timezone, Prev: skip, Up: CSV + +9.7 '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 + + Note currently there is no locale awareness for things like '%b', and +setting LC_TIME won't help. + + +File: hledger.info, Node: timezone, Next: newest-first, Prev: date-format, Up: CSV + +9.8 'timezone' +============== + +timezone TIMEZONE + + When CSV contains date-times that are implicitly in some time zone +other than yours, but containing no explicit time zone information, you +can use this rule to declare the CSV's native time zone, which helps +prevent off-by-one dates. + + When the CSV date-times do contain time zone information, you don't +need this rule; instead, use '%Z' in 'date-format' (or '%z', '%EZ', +'%Ez'; see the formatTime link above). + + In either of these cases, hledger will do a time-zone-aware +conversion, localising the CSV date-times to your current system time +zone. If you prefer to localise to some other time zone, eg for +reproducibility, you can (on unix at least) set the output timezone with +the TZ environment variable, eg: + +$ TZ=-1000 hledger print -f foo.csv # or TZ=-1000 hledger import foo.csv + + 'timezone' currently does not understand timezone names, except +"UTC", "GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT". +For others, use numeric format: +HHMM or -HHMM. + + +File: hledger.info, Node: newest-first, Next: intra-day-reversed, Prev: timezone, Up: CSV + +9.9 'newest-first' +================== + +hledger tries to ensure that the generated transactions will be ordered +chronologically, including same-day transactions. Usually it can +auto-detect how the CSV records are ordered. But if it encounters CSV +where all records are on the same date, it assumes that the records are +oldest first. If in fact the CSV's records are normally newest first, +like: + +2022-10-01, txn 3... +2022-10-01, txn 2... +2022-10-01, txn 1... + + you can add the 'newest-first' rule to help hledger generate the +transactions in correct order. + +# same-day CSV records are newest first +newest-first + + +File: hledger.info, Node: intra-day-reversed, Next: decimal-mark, Prev: newest-first, Up: CSV + +9.10 'intra-day-reversed' +========================= + +If CSV records within a single day are ordered opposite to the overall +record order, you can add the 'intra-day-reversed' rule to improve the +order of journal entries. Eg, here the overall record order is newest +first, but same-day records are oldest first: + +2022-10-02, txn 3... +2022-10-02, txn 4... +2022-10-01, txn 1... +2022-10-01, txn 2... + +# transactions within each day are reversed with respect to the overall date order +intra-day-reversed + + +File: hledger.info, Node: decimal-mark, Next: fields list, Prev: intra-day-reversed, Up: CSV + +9.11 'decimal-mark' +=================== + +decimal-mark . + + or: + +decimal-mark , + + hledger automatically accepts either period or comma as a decimal +mark when parsing numbers (cf Amounts). However if any numbers in the +CSV contain digit group marks, such as thousand-separating commas, you +should declare the decimal mark explicitly with this rule, to avoid +misparsed numbers. + + +File: hledger.info, Node: fields list, Next: Field assignment, Prev: decimal-mark, Up: CSV + +9.12 'fields' list +================== + +fields FIELDNAME1, FIELDNAME2, ... + + A fields list (the word 'fields' followed by comma-separated field +names) is optional, but convenient. It does two things: + + 1. It names the CSV field in each column. This can be convenient if + you are referencing them in other rules, so you can say + '%SomeField' instead of remembering '%13'. + + 2. Whenever you use one of the special hledger field names (described + below), it assigns the CSV value in this position to that hledger + field. This is the quickest way to populate hledger's fields and + build a transaction. + + Here's an example that says "use the 1st, 2nd and 4th fields as the +transaction's date, description and amount; name the last two fields for +later reference; and ignore the others": + +fields date, description, , amount, , , somefield, anotherfield + + In a fields list, the separator is always comma; it is unrelated to +the CSV file's separator. Also: + + * There must be least two items in the list (at least one comma). + * Field names may not contain spaces. Spaces before/after field + names are optional. + * Field names may contain '_' (underscore) or '-' (hyphen). + * Fields you don't care about can be given a dummy name or an empty + name. + + If the CSV contains column headings, it's convenient to use these for +your field names, suitably modified (eg lower-cased with spaces replaced +by underscores). + + Sometimes you may want to alter a CSV field name to avoid assigning +to a hledger field with the same name. Eg you could call the CSV's +"balance" field 'balance_' to avoid directly setting hledger's 'balance' +field (and generating a balance assertion). + + +File: hledger.info, Node: Field assignment, Next: Field names, Prev: fields list, Up: CSV + +9.13 Field assignment +===================== + +HLEDGERFIELD FIELDVALUE + + Field assignments are the more flexible way to assign CSV values to +hledger fields. They can be used instead of or in addition to a fields +list (see above). + + To assign a value to a hledger field, write the field name (any of +the standard hledger field/pseudo-field names, defined below), a space, +followed by a text value on the same line. This text value may +interpolate CSV fields, referenced either by their 1-based position in +the CSV record ('%N') or by the name they were given in the fields list +('%CSVFIELD'), and regular expression match groups ('\N'). + + Some examples: + +# set the amount to the 4th CSV field, with " USD" appended +amount %4 USD + +# combine three fields to make a comment, containing note: and date: tags +comment note: %somefield - %anotherfield, date: %1 + + Tips: + + * Interpolation strips outer whitespace (so a CSV value like '" 1 "' + becomes '1' when interpolated) (#1051). + * Interpolations always refer to a CSV field - you can't interpolate + a hledger field. (See Referencing other fields below). + + +File: hledger.info, Node: Field names, Next: if block, Prev: Field assignment, Up: CSV + +9.14 Field names +================ + +Note the two kinds of field names mentioned here, and used only in +hledger CSV rules files: + + 1. *CSV field names* ('CSVFIELD' in these docs): you can optionally + name the CSV columns for easy reference (since hledger doesn't yet + automatically recognise column headings in a CSV file), by writing + arbitrary names in a 'fields' list, eg: + + fields When, What, Some_Id, Net, Total, Foo, Bar + + 2. Special *hledger field names* ('HLEDGERFIELD' in these docs): you + must set at least some of these to generate the hledger transaction + from a CSV record, by writing them as the left hand side of a field + assignment, eg: + + date %When + code %Some_Id + description %What + comment %Foo %Bar + amount1 $ %Total + + or directly in a 'fields' list: + + fields date, description, code, , amount1, Foo, Bar + currency $ + comment %Foo %Bar + + Here are all the special hledger field names available, and what +happens when you assign values to them: + +* Menu: + +* date field:: +* date2 field:: +* status field:: +* code field:: +* description field:: +* comment field:: +* account field:: +* amount field:: +* currency field:: +* balance field:: + + +File: hledger.info, Node: date field, Next: date2 field, Up: Field names + +9.14.1 date field +----------------- + +Assigning to 'date' sets the transaction date. + + +File: hledger.info, Node: date2 field, Next: status field, Prev: date field, Up: Field names + +9.14.2 date2 field +------------------ + +'date2' sets the transaction's secondary date, if any. + + +File: hledger.info, Node: status field, Next: code field, Prev: date2 field, Up: Field names + +9.14.3 status field +------------------- + +'status' sets the transaction's status, if any. + + +File: hledger.info, Node: code field, Next: description field, Prev: status field, Up: Field names + +9.14.4 code field +----------------- + +'code' sets the transaction's code, if any. + + +File: hledger.info, Node: description field, Next: comment field, Prev: code field, Up: Field names + +9.14.5 description field +------------------------ + +'description' sets the transaction's description, if any. + + +File: hledger.info, Node: comment field, Next: account field, Prev: description field, Up: Field names + +9.14.6 comment field +-------------------- + +'comment' sets the transaction's comment, if any. + + 'commentN', where N is a number, sets the Nth posting's comment. + + You can assign multi-line comments by writing literal '\n' in the +code. A comment starting with '\n' will begin on a new line. + + Comments can contain tags, as usual. + + Posting comments can also contain a posting date. A secondary date, +or a year-less date, will be ignored. + + +File: hledger.info, Node: account field, Next: amount field, Prev: comment field, Up: Field names + +9.14.7 account field +-------------------- + +Assigning to 'accountN', where N is 1 to 99, sets the account name of +the Nth posting, and causes that posting to be generated. + + Most often there are two postings, so you'll want to set 'account1' +and 'account2'. Typically 'account1' is associated with the CSV file, +and is set once with a top-level assignment, while 'account2' is set +based on each transaction's description, in conditional rules. + + If a posting's account name is left unset but its amount is set (see +below), a default account name will be chosen (like "expenses:unknown" +or "income:unknown"). + + +File: hledger.info, Node: amount field, Next: currency field, Prev: account field, Up: Field names + +9.14.8 amount field +------------------- + +There are several ways to set posting amounts from CSV, useful in +different situations. + + 1. *'amount'* is the oldest and simplest. Assigning to this sets the + amount of the first and second postings. In the second posting, + the amount will be negated; also, if it has a cost attached, it + will be converted to cost. + + 2. *'amount-in'* and *'amount-out'* work exactly like the above, but + should be used when the CSV has two amount fields (such as "Debit" + and "Credit", or "Inflow" and "Outflow"). Whichever field has a + non-zero value will be used as the amount of the first and second + postings. Here are some tips to avoid confusion: + + * It's not "amount-in for posting 1 and amount-out for posting + 2", it is "extract a single amount from the amount-in or + amount-out field, and use that for posting 1 and (negated) for + posting 2". + * Don't use both 'amount' and 'amount-in'/'amount-out' in the + same rules file; choose based on whether the amount is in a + single CSV field or spread across two fields. + * In each record, at most one of the two CSV fields should + contain a non-zero amount; the other field must contain a zero + or nothing. + * hledger assumes both CSV fields contain unsigned numbers, and + it automatically negates the amount-out values. + * If the data doesn't fit these requirements, you'll probably + need an if rule (see below). + + 3. *'amountN'* (where N is a number from 1 to 99) sets the amount of + only a single posting: the Nth posting in the transaction. You'll + usually need at least two such assignments to make a balanced + transaction. You can also generate more than two postings, to + represent more complex transactions. The posting numbers don't + have to be consecutive; with if rules, higher posting numbers can + be useful to ensure a certain order of postings. + + 4. *'amountN-in'* and *'amountN-out'* work exactly like the above, but + should be used when the CSV has two amount fields. This is + analogous to 'amount-in' and 'amount-out', and those tips also + apply here. + + 5. Remember that a 'fields' list can also do assignments. So in a + fields list if you name a CSV field "amount", that counts as + assigning to 'amount'. (If you don't want that, call it something + else in the fields list, like "amount_".) + + 6. The above don't handle every situation; if you need more + flexibility, use an 'if' rule to set amounts conditionally. See + "Working with CSV > Setting amounts" below for more on this and on + amount-setting generally. + + +File: hledger.info, Node: currency field, Next: balance field, Prev: amount field, Up: Field names + +9.14.9 currency field +--------------------- + +'currency' sets a currency symbol, to be prepended to all postings' +amounts. You can use this if the CSV amounts do not have a currency +symbol, eg if it is in a separate column. + + 'currencyN' prepends a currency symbol to just the Nth posting's +amount. + + +File: hledger.info, Node: balance field, Prev: currency field, Up: Field names + +9.14.10 balance field +--------------------- + +'balanceN' sets a balance assertion amount (or if the posting amount is +left empty, a balance assignment) on posting N. + + 'balance' is a compatibility spelling for hledger <1.17; it is +equivalent to 'balance1'. + + You can adjust the type of assertion/assignment with the +'balance-type' rule (see below). + + See the Working with CSV tips below for more about setting amounts +and currency. + + +File: hledger.info, Node: if block, Next: Matchers, Prev: Field names, Up: CSV + +9.15 'if' block +=============== + +Rules can be applied conditionally, depending on patterns in the CSV +data. This allows flexibility; in particular, it is how you can +categorise transactions, selecting an appropriate account name based on +their description (for example). There are two ways to write +conditional rules: "if blocks", described here, and "if tables", +described below. + + An if block is the word 'if' and one or more "matcher" expressions +(can be a word or phrase), one per line, starting either on the same or +next line; followed by one or more indented rules. Eg, + +if MATCHER + RULE + + or + +if +MATCHER +MATCHER +MATCHER + RULE + RULE + + If any of the matchers succeeds, all of the indented rules will be +applied. They are usually field assignments, but the following special +rules may also be used within an if block: + + * 'skip' - skips the matched CSV record (generating no transaction + from it) + * 'end' - skips the rest of the current CSV file. + + Some examples: + +# if the record contains "groceries", set account2 to "expenses:groceries" +if groceries + account2 expenses:groceries + +# if the record contains any of these phrases, set account2 and a transaction comment as shown +if +monthly service fee +atm transaction fee +banking thru software + account2 expenses:business:banking + comment XXX deductible ? check it + +# if an empty record is seen (assuming five fields), ignore the rest of the CSV file +if ,,,, + end + + +File: hledger.info, Node: Matchers, Next: if table, Prev: if block, Up: CSV + +9.16 Matchers +============= + +There are two kinds of matcher: + + 1. A whole record matcher is simplest: it is just a word, single-line + text fragment, or other regular expression, which hledger will try + to match case-insensitively anywhere within the CSV record. + Eg: 'whole foods'. + + 2. A field matcher has a percent-prefixed CSV field number or name + before the pattern. + Eg: '%3 whole foods' or '%description whole foods'. + hledger will try to match the pattern just within the named CSV + field. + + When using these, there's two things to be aware of: + + 1. Whole record matchers don't see the exact original record; they see + a reconstruction of it, in which values are comma-separated, and + quotes enclosing values and whitespace outside those quotes are + removed. + Eg when reading an SSV record like: '2023-01-01 ; "Acme, Inc. " ; + 1,000' + the whole record matcher sees instead: '2023-01-01,Acme, Inc. + ,1,000' + + 2. Field matchers expect either a CSV field number, or a CSV field + name declared with 'fields'. (Don't use a hledger field name here, + unless it is also a CSV field name.) A non-CSV field name will + cause the matcher to match against '""' (the empty string), and + does not raise an error, allowing easier reuse of common rules with + different CSV files. + + You can also prefix a matcher with '!' (and optional space) to negate +it. Eg '! whole foods', '! %3 whole foods', '!%description whole foods' +will match if "whole foods" is NOT present. _Added in 1.32._ + + The pattern is, as usual in hledger, a POSIX extended regular +expression that also supports GNU word boundaries ('\b', '\B', '\<', +'\>') and nothing else. If you have trouble with it, see "Regular +expressions" in the hledger manual +(https://hledger.org/hledger.html#regular-expressions). + +* Menu: + +* Multiple matchers:: +* Match groups:: + + +File: hledger.info, Node: Multiple matchers, Next: Match groups, Up: Matchers + +9.16.1 Multiple matchers +------------------------ + +When an if block has multiple matchers, each on its own line, + + * By default they are OR'd (any of them can match). + * Matcher lines beginning with '&' (or '&&', _since 1.42_) are AND'ed + with the matcher above (all in the AND'ed group must match). + * Matcher lines beginning with '& !' (_since 1.41_, or '&& !', _since + 1.42_) are first negated and then AND'ed with the matcher above. + + You can also combine multiple matchers one the same line separated by +'&&' (AND) or '&& !' (AND NOT). Eg '%description amazon && %date +2025-01-01' will match only when the description field contains "amazon" +and the date field contains "2025-01-01". _Added in 1.42._ + + +File: hledger.info, Node: Match groups, Prev: Multiple matchers, Up: Matchers + +9.16.2 Match groups +------------------- + +_Added in 1.32_ + + Matchers can define match groups: parenthesised portions of the +regular expression which are available for reference in field +assignments. Groups are enclosed in regular parentheses ('(' and ')') +and can be nested. Each group is available in field assignments using +the token '\N', where N is an index into the match groups for this +conditional block (e.g. '\1', '\2', etc.). + + Example: Warp credit card payment postings to the beginning of the +billing period (Month start), to match how they are presented in +statements, using posting dates: + +if %date (....-..)-.. + comment2 date:\1-01 + + Another example: Read the expense account from the CSV field, but +throw away a prefix: + +if %account1 liabilities:family:(expenses:.*) + account1 \1 + + +File: hledger.info, Node: if table, Next: balance-type, Prev: Matchers, Up: CSV + +9.17 'if' table +=============== + +"if tables" are an alternative to if blocks; they can express many +matchers and field assignments in a more compact tabular format, like +this: + +if,HLEDGERFIELD1,HLEDGERFIELD2,... +MATCHERA,VALUE1,VALUE2,... +MATCHERB && MATCHERC,VALUE1,VALUE2,... (*since 1.42*) +; Comment line that explains MATCHERD +MATCHERD,VALUE1,VALUE2,... + + + The first character after 'if' is taken to be this if table's field +separator. It is unrelated to the separator used in the CSV file. It +should be a non-alphanumeric character like ',' or '|' that does not +appear anywhere else in the table (it should not be used in field names +or matchers or values, and it cannot be escaped with a backslash). + + Each line must contain the same number of separators; empty values +are allowed. Whitespace can be used in the matcher lines for +readability (but not in the if line, currently). You can use the +comment lines in the table body. The table must be terminated by an +empty line (or end of file). + + An if table like the above is interpreted as follows: try all of the +lines with matchers; whenever a line with matchers succeeds, assign all +of the values on that line to the corresponding hledger fields; If +multiple lines match, later lines will override fields assigned by the +earlier ones - just like the sequence of 'if' blocks would behave. + + If table presented above is equivalent to this sequence of if blocks: + +if MATCHERA + HLEDGERFIELD1 VALUE1 + HLEDGERFIELD2 VALUE2 + ... + +if MATCHERB && MATCHERC + HLEDGERFIELD1 VALUE1 + HLEDGERFIELD2 VALUE2 + ... + +; Comment line which explains MATCHERD +if MATCHERD + HLEDGERFIELD1 VALUE1 + HLEDGERFIELD2 VALUE2 + ... + + Example: + +if,account2,comment +atm transaction fee,expenses:business:banking,deductible? check it +%description groceries,expenses:groceries, +;; Comment line that desribes why this particular date is special +2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out + + +File: hledger.info, Node: balance-type, Next: include, Prev: if table, Up: CSV + +9.18 'balance-type' +=================== + +Balance assertions generated by assigning to balanceN are of the simple +'=' type by default, which is a single-commodity, subaccount-excluding +assertion. You may find the subaccount-including variants more useful, +eg if you have created some virtual subaccounts of checking to help with +budgeting. You can select a different type of assertion with the +'balance-type' rule: + +# balance assertions will consider all commodities and all subaccounts +balance-type ==* + + Here are the balance assertion types for quick reference: + += single commodity, exclude subaccounts +=* single commodity, include subaccounts +== multi commodity, exclude subaccounts +==* multi commodity, include subaccounts + + +File: hledger.info, Node: include, Next: Working with CSV, Prev: balance-type, Up: CSV + +9.19 'include' +============== + +include RULESFILE + + This includes the contents of another CSV rules file at this point. +'RULESFILE' is an absolute file path or a path relative to the current +file's directory. This can be useful for sharing common rules between +several rules files, eg: + +# someaccount.csv.rules + +## someaccount-specific rules +fields date,description,amount +account1 assets:someaccount +account2 expenses:misc + +## common rules +include categorisation.rules + + +File: hledger.info, Node: Working with CSV, Next: CSV rules examples, Prev: include, Up: CSV + +9.20 Working with CSV +===================== + +Some tips: + +* Menu: + +* Rapid feedback:: +* Valid CSV:: +* File Extension:: +* Reading CSV from standard input:: +* Reading multiple CSV files:: +* Reading files specified by rule:: +* Valid transactions:: +* Deduplicating importing:: +* Setting amounts:: +* Amount signs:: +* Setting currency/commodity:: +* Amount decimal places:: +* Referencing other fields:: +* How CSV rules are evaluated:: +* Well factored rules:: + + +File: hledger.info, Node: Rapid feedback, Next: Valid CSV, Up: Working with CSV + +9.20.1 Rapid feedback +--------------------- + +It's a good idea to get rapid feedback while creating/troubleshooting +CSV rules. Here's a good way, using entr from eradman.com/entrproject: + +$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC' + + A desc: query (eg) is used to select just one, or a few, transactions +of interest. "bash -c" is used to run multiple commands, so we can echo +a separator each time the command re-runs, making it easier to read the +output. + + +File: hledger.info, Node: Valid CSV, Next: File Extension, Prev: Rapid feedback, Up: Working with CSV + +9.20.2 Valid CSV +---------------- + +Note that hledger will only accept valid CSV conforming to RFC 4180, and +equivalent SSV and TSV formats (like RFC 4180 but with semicolon or tab +as separators). This means, eg: + + * Values may be enclosed in double quotes, or not. Enclosing in + single quotes is not allowed. (Eg ''A','B'' is rejected.) + * When values are enclosed in double quotes, spaces outside the + quotes are not allowed. (Eg '"A", "B"' is rejected.) + * When values are not enclosed in quotes, they may not contain double + quotes. (Eg 'A"A, B' is rejected.) + + If your CSV/SSV/TSV is not valid in this sense, you'll need to +transform it before reading with hledger. Try using sed, or a more +permissive CSV parser like python's csv lib. + + +File: hledger.info, Node: File Extension, Next: Reading CSV from standard input, Prev: Valid CSV, Up: Working with CSV + +9.20.3 File Extension +--------------------- + +To help hledger choose the CSV file reader and show the right error +messages (and choose the right field separator character by default), +it's best if CSV/SSV/TSV files are named with a '.csv', '.ssv' or '.tsv' +filename extension. (More about this at Data formats.) + + When reading files with the "wrong" extension, you can ensure the CSV +reader (and the default field separator) by prefixing the file path with +'csv:', 'ssv:' or 'tsv:': Eg: + +$ hledger -f ssv:foo.dat print + + You can also override the default field separator with a separator +rule if needed. + + +File: hledger.info, Node: Reading CSV from standard input, Next: Reading multiple CSV files, Prev: File Extension, Up: Working with CSV + +9.20.4 Reading CSV from standard input +-------------------------------------- + +You'll need the file format prefix when reading CSV from stdin also, +since hledger assumes journal format by default. Eg: + +$ cat foo.dat | hledger -f ssv:- print + + +File: hledger.info, Node: Reading multiple CSV files, Next: Reading files specified by rule, Prev: Reading CSV from standard input, Up: Working with CSV + +9.20.5 Reading multiple CSV files +--------------------------------- + +If you use multiple '-f' options to read multiple CSV files at once, +hledger will look for a correspondingly-named rules file for each CSV +file. But if you specify a rules file with '--rules', that rules file +will be used for all the CSV files. + + +File: hledger.info, Node: Reading files specified by rule, Next: Valid transactions, Prev: Reading multiple CSV files, Up: Working with CSV + +9.20.6 Reading files specified by rule +-------------------------------------- + +Instead of specifying a CSV file in the command line, you can specify a +rules file, as in 'hledger -f foo.csv.rules CMD'. By default this will +read data from foo.csv in the same directory, but you can add a source +rule to specify a different data file, perhaps located in your web +browser's download directory. + + This feature was added in hledger 1.30, so you won't see it in most +CSV rules examples. But it helps remove some of the busywork of +managing CSV downloads. Most of your financial institutions's default +CSV filenames are different and can be recognised by a glob pattern. So +you can put a rule like 'source Checking1*.csv' in +foo-checking.csv.rules, and then periodically follow a workflow like: + + 1. Download CSV from Foo's website, using your browser's defaults + 2. Run 'hledger import foo-checking.csv.rules' to import any new + transactions + + After import, you can: discard the CSV, or leave it where it is for a +while, or move it into your archives, as you prefer. If you do nothing, +next time your browser will save something like Checking1-2.csv, and +hledger will use that because of the '*' wild card and because it is the +most recent. + + +File: hledger.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading files specified by rule, Up: Working with CSV + +9.20.7 Valid transactions +------------------------- + +After reading a CSV file, hledger post-processes and validates the +generated journal entries as it would for a journal file - balancing +them, applying balance assignments, and canonicalising amount styles. +Any errors at this stage will be reported in the usual way, displaying +the problem entry. + + There is one exception: balance assertions, if you have generated +them, will not be checked, since normally these will work only when the +CSV data is part of the main journal. If you do need to check balance +assertions generated from CSV right away, pipe into another hledger: + +$ hledger -f file.csv print | hledger -f- print + + +File: hledger.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: Working with CSV + +9.20.8 Deduplicating, importing +------------------------------- + +When you download a CSV file periodically, eg to get your latest bank +transactions, the new file may overlap with the old one, containing some +of the same records. + + The import command will (a) detect the new transactions, and (b) +append just those transactions to your main journal. It is idempotent, +so you don't have to remember how many times you ran it or with which +version of the CSV. (It keeps state in a hidden '.latest.FILE.csv' +file.) This is the easiest way to import CSV data. Eg: + +# download the latest CSV files, then run this command. +# Note, no -f flags needed here. +$ hledger import *.csv [--dry] + + This method works for most CSV files. (Where records have a stable +chronological order, and new records appear only at the new end.) + + A number of other tools and workflows, hledger-specific and +otherwise, exist for converting, deduplicating, classifying and managing +CSV data. See: + + * https://hledger.org/cookbook.html#setups-and-workflows + * https://plaintextaccounting.org -> data import/conversion + + +File: hledger.info, Node: Setting amounts, Next: Amount signs, Prev: Deduplicating importing, Up: Working with CSV + +9.20.9 Setting amounts +---------------------- + +Continuing from amount field above, here are more tips for +amount-setting: + + 1. *If the amount is in a single CSV field:* + + a. *If its sign indicates direction of flow:* + Assign it to 'amountN', to set the Nth posting's amount. N is + usually 1 or 2 but can go up to 99. + + b. *If another field indicates direction of flow:* + Use one or more conditional rules to set the appropriate + amount sign. Eg: + + # assume a withdrawal unless Type contains "deposit": + amount1 -%Amount + if %Type deposit + amount1 %Amount + + 2. *If the amount is in two CSV fields (such as Debit and Credit, or + In and Out):* + + a. *If both fields are unsigned:* + Assign one field to 'amountN-in' and the other to + 'amountN-out'. hledger will automatically negate the "out" + field, and will use whichever field value is non-zero as + posting N's amount. + + b. *If either field is signed:* + You will probably need to override hledger's sign for one or + the other field, as in the following example: + + # Negate the -out value, but only if it is not empty: + fields date, description, amount1-in, amount1-out + if %amount1-out [1-9] + amount1-out -%amount1-out + + c. *If both fields can contain a non-zero value (or both can be + empty):* + The -in/-out rules normally choose the value which is + non-zero/non-empty. Some value pairs can be ambiguous, such + as '1' and 'none'. For such cases, use conditional rules to + help select the amount. Eg, to handle the above you could + select the value containing non-zero digits: + + fields date, description, in, out + if %in [1-9] + amount1 %in + if %out [1-9] + amount1 %out + + 3. *If you want posting 2's amount converted to cost:* + Use the unnumbered 'amount' (or 'amount-in' and 'amount-out') + syntax. + + 4. *If the CSV has only balance amounts, not transaction amounts:* + Assign to 'balanceN', to set a balance assignment on the Nth + posting, causing the posting's amount to be calculated + automatically. 'balance' with no number is equivalent to + 'balance1'. In this situation hledger is more likely to guess the + wrong default account name, so you may need to set that explicitly. + + +File: hledger.info, Node: Amount signs, Next: Setting currency/commodity, Prev: Setting amounts, Up: Working with CSV + +9.20.10 Amount signs +-------------------- + +There is some special handling making it easier to parse and to reverse +amount signs. (This only works for whole amounts, not for cost amounts +such as COST in 'amount1 AMT @ COST'): + + * *If an amount value begins with a plus sign:* + that will be removed: '+AMT' becomes 'AMT' + + * *If an amount value is parenthesised:* + it will be de-parenthesised and sign-flipped: '(AMT)' becomes + '-AMT' + + * *If an amount value has two minus signs (or two sets of + parentheses, or a minus sign and parentheses):* + they cancel out and will be removed: '--AMT' or '-(AMT)' becomes + 'AMT' + + * *If an amount value contains just a sign (or just a set of + parentheses):* + that is removed, making it an empty value. '"+"' or '"-"' or + '"()"' becomes '""'. + + It's not possible (without preprocessing the CSV) to set an amount to +its absolute value, ie discard its sign. + + +File: hledger.info, Node: Setting currency/commodity, Next: Amount decimal places, Prev: Amount signs, Up: Working with CSV + +9.20.11 Setting currency/commodity +---------------------------------- + +If the currency/commodity symbol is included in the CSV's amount +field(s): + +2023-01-01,foo,$123.00 + + you don't have to do anything special for the commodity symbol, it +will be assigned as part of the amount. Eg: + +fields date,description,amount + +2023-01-01 foo + expenses:unknown $123.00 + income:unknown $-123.00 + + If the currency is provided as a separate CSV field: + +2023-01-01,foo,USD,123.00 + + You can assign that to the 'currency' pseudo-field, which has the +special effect of prepending itself to every amount in the transaction +(on the left, with no separating space): + +fields date,description,currency,amount + +2023-01-01 foo + expenses:unknown USD123.00 + income:unknown USD-123.00 + + Or, you can use a field assignment to construct the amount yourself, +with more control. Eg to put the symbol on the right, and separated by +a space: + +fields date,description,cur,amt +amount %amt %cur + +2023-01-01 foo + expenses:unknown 123.00 USD + income:unknown -123.00 USD + + Note we used a temporary field name ('cur') that is not 'currency' - +that would trigger the prepending effect, which we don't want here. + + +File: hledger.info, Node: Amount decimal places, Next: Referencing other fields, Prev: Setting currency/commodity, Up: Working with CSV + +9.20.12 Amount decimal places +----------------------------- + +When you are reading CSV data, eg with a command like 'hledger -f +foo.csv print', hledger will infer each commodity's decimal precision +(and other commodity display styles) from the amounts - much as when +reading a journal file without 'commodity' directives (see the link). + + Note, the commodity styles are not inferred from the numbers in the +original CSV data; rather, they are inferred from the amounts generated +by the CSV rules. + + When you are importing CSV data with the 'import' command, eg +'hledger import foo.csv', there's another step: 'import' tries to make +the new entries conform to the journal's existing styles. So for each +commodity - let's say it's EUR - 'import' will choose: + + 1. the style declared for EUR by a 'commodity' directive in the + journal + 2. otherwise, the style inferred from EUR amounts in the journal + 3. otherwise, the style inferred from EUR amounts generated by the CSV + rules. + + TLDR: if 'import' is not generating the precisions or styles you +want, add a 'commodity' directive to specify them. + + +File: hledger.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Amount decimal places, Up: Working with CSV + +9.20.13 Referencing other fields +-------------------------------- + +In field assignments, you can interpolate only CSV fields, not hledger +fields. In the example below, there's both a CSV field and a hledger +field named amount1, but %amount1 always means the CSV field, not the +hledger field: + +# Name the third CSV field "amount1" +fields date,description,amount1 + +# Set hledger's amount1 to the CSV amount1 field followed by USD +amount1 %amount1 USD + +# Set comment to the CSV amount1 (not the amount1 assigned above) +comment %amount1 + + Here, since there's no CSV amount1 field, %amount1 will produce a +literal "amount1": + +fields date,description,csvamount +amount1 %csvamount USD +# Can't interpolate amount1 here +comment %amount1 + + When there are multiple field assignments to the same hledger field, +only the last one takes effect. Here, comment's value will be be B, or +C if "something" is matched, but never A: + +comment A +comment B +if something + comment C + + +File: hledger.info, Node: How CSV rules are evaluated, Next: Well factored rules, Prev: Referencing other fields, Up: Working with CSV + +9.20.14 How CSV rules are evaluated +----------------------------------- + +Here's how to think of CSV rules being evaluated. If you get a +confusing error while reading a CSV file, it may help to try to +understand which of these steps is failing: + + 1. Any included rules files are inlined, from top to bottom, depth + first (scanning each included file for further includes, + recursively, before proceeding). + + 2. Top level rules ('date-format', 'fields', 'newest-first', 'skip' + etc) are read, top to bottom. "Top level rules" means + non-conditional rules. If a rule occurs more than once, the last + one wins; except for 'skip'/'end' rules, where the first one wins. + + 3. The CSV file is read as text. Any non-ascii characters will be + decoded using the text encoding specified by the 'encoding' rule, + otherwise the system locale's text encoding. + + 4. Any top-level skip or end rule is applied. 'skip [N]' immediately + skips the current or next N CSV records; 'end' immediately skips + all remaining CSV records (not normally used at top level). + + 5. Now any remaining CSV records are processed. For each CSV record, + in file order: + + * Is there a conditional skip/end rule that applies for this + record ? Search the 'if' blocks, from top to bottom, for a + succeeding one containing a 'skip' or 'end' rule. If found, + skip the specified number of CSV records, then continue at 5. + Otherwise... + + * Do some basic validation on this CSV record (eg, check that it + has at least two fields). + + * For each hledger field ('date', 'description', 'account1', + etc.): + + 1. Get the field's assigned value, first searching top level + assignments, made directly or by the 'fields' rule, then + assignments made inside succeeding 'if' blocks. If there + are more than one, the last one wins. + + 2. Compute the field's actual value (as text), by + interpolating any %CSVFIELD references within the + assigned value; or by choosing a default value if there + was no assignment. + + * Generate a hledger transaction from the hledger field values, + parsing them if needed (eg from text to an amount). + + This is all done by the CSV reader, one of several readers hledger +can use to read transactions from an input file. When all input files +have been read successfully, their transactions are passed to whichever +hledger command the user specified. + + +File: hledger.info, Node: Well factored rules, Prev: How CSV rules are evaluated, Up: Working with CSV + +9.20.15 Well factored rules +--------------------------- + +Some things than can help reduce duplication and complexity in rules +files: + + * Extracting common rules usable with multiple CSV files into a + 'common.rules', and adding 'include common.rules' to each CSV's + rules file. + + * Splitting if blocks into smaller if blocks, extracting the + frequently used parts. + + +File: hledger.info, Node: CSV rules examples, Prev: Working with CSV, Up: CSV + +9.21 CSV rules examples +======================= + +* Menu: + +* Bank of Ireland:: +* Coinbase:: +* Amazon:: +* Paypal:: + + +File: hledger.info, Node: Bank of Ireland, Next: Coinbase, Up: CSV rules examples + +9.21.1 Bank of Ireland +---------------------- + +Here's a CSV with two amount fields (Debit and Credit), and a balance +field, which we can use to add balance assertions, which is not +necessary but provides extra error checking: + +Date,Details,Debit,Credit,Balance +07/12/2012,LODGMENT 529898,,10.0,131.21 +07/12/2012,PAYMENT,5,,126 + +# bankofireland-checking.csv.rules + +# skip the header line +skip + +# name the csv fields, and assign some of them as journal entry fields +fields date, description, amount-out, amount-in, balance + +# We generate balance assertions by assigning to "balance" +# above, but you may sometimes need to remove these because: +# +# - the CSV balance differs from the true balance, +# by up to 0.0000000000005 in my experience +# +# - it is sometimes calculated based on non-chronological ordering, +# eg when multiple transactions clear on the same day + +# date is in UK/Ireland format +date-format %d/%m/%Y + +# set the currency +currency EUR + +# set the base account for all txns +account1 assets:bank:boi:checking + +$ hledger -f bankofireland-checking.csv print +2012-12-07 LODGMENT 529898 + assets:bank:boi:checking EUR10.0 = EUR131.2 + income:unknown EUR-10.0 + +2012-12-07 PAYMENT + assets:bank:boi:checking EUR-5.0 = EUR126.0 + expenses:unknown EUR5.0 + + The balance assertions don't raise an error above, because we're +reading directly from CSV, but they will be checked if these entries are +imported into a journal file. + + +File: hledger.info, Node: Coinbase, Next: Amazon, Prev: Bank of Ireland, Up: CSV rules examples + +9.21.2 Coinbase +--------------- + +A simple example with some CSV from Coinbase. The spot price is +recorded using cost notation. The legacy 'amount' field name +conveniently sets amount 2 (posting 2's amount) to the total cost. + +# Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes +# 2021-12-30T06:57:59Z,Receive,USDC,100,GBP,0.740000,"","","","Received 100.00 USDC from an external account" + +# coinbase.csv.rules +skip 1 +fields Timestamp,Transaction_Type,Asset,Quantity_Transacted,Spot_Price_Currency,Spot_Price_at_Transaction,Subtotal,Total,Fees_Spread,Notes +date %Timestamp +date-format %Y-%m-%dT%T%Z +description %Notes +account1 assets:coinbase:cc +amount %Quantity_Transacted %Asset @ %Spot_Price_at_Transaction %Spot_Price_Currency + +$ hledger print -f coinbase.csv +2021-12-30 Received 100.00 USDC from an external account + assets:coinbase:cc 100 USDC @ 0.740000 GBP + income:unknown -74.000000 GBP + + +File: hledger.info, Node: Amazon, Next: Paypal, Prev: Coinbase, Up: CSV rules examples + +9.21.3 Amazon +------------- + +Here we convert amazon.com order history, and use an if block to +generate a third posting if there's a fee. (In practice you'd probably +get this data from your bank instead, but it's an example.) + +"Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID" +"Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL" +"Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL" + +# amazon-orders.csv.rules + +# skip one header line +skip 1 + +# name the csv fields, and assign the transaction's date, amount and code. +# Avoided the "status" and "amount" hledger field names to prevent confusion. +fields date, _, toorfrom, name, amzstatus, amzamount, fees, code + +# how to parse the date +date-format %b %-d, %Y + +# combine two fields to make the description +description %toorfrom %name + +# save the status as a tag +comment status:%amzstatus + +# set the base account for all transactions +account1 assets:amazon +# leave amount1 blank so it can balance the other(s). +# I'm assuming amzamount excludes the fees, don't remember + +# set a generic account2 +account2 expenses:misc +amount2 %amzamount +# and maybe refine it further: +#include categorisation.rules + +# add a third posting for fees, but only if they are non-zero. +if %fees [1-9] + account3 expenses:fees + amount3 %fees + +$ hledger -f amazon-orders.csv print +2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed + assets:amazon + expenses:misc $20.00 + +2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed + assets:amazon + expenses:misc $25.00 + expenses:fees $1.00 + + +File: hledger.info, Node: Paypal, Prev: Amazon, Up: CSV rules examples + +9.21.4 Paypal +------------- + +Here's a real-world rules file for (customised) Paypal CSV, with some +Paypal-specific rules, and a second rules file included: + +"Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note" +"10/01/2019","03:46:20","PDT","Calm Radio","Subscription Payment","Completed","USD","-6.99","0.00","-6.99","simon@joyful.com","memberships@calmradio.com","60P57143A8206782E","MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month","","I-R8YLY094FJYR","","-6.99","" +"10/01/2019","03:46:20","PDT","","Bank Deposit to PP Account ","Pending","USD","6.99","0.00","6.99","","simon@joyful.com","0TU1544T080463733","","","60P57143A8206782E","","0.00","" +"10/01/2019","08:57:01","PDT","Patreon","PreApproved Payment Bill User Payment","Completed","USD","-7.00","0.00","-7.00","simon@joyful.com","support@patreon.com","2722394R5F586712G","Patreon* Membership","","B-0PG93074E7M86381M","","-7.00","" +"10/01/2019","08:57:01","PDT","","Bank Deposit to PP Account ","Pending","USD","7.00","0.00","7.00","","simon@joyful.com","71854087RG994194F","Patreon* Membership","","2722394R5F586712G","","0.00","" +"10/19/2019","03:02:12","PDT","Wikimedia Foundation, Inc.","Subscription Payment","Completed","USD","-2.00","0.00","-2.00","simon@joyful.com","tle@wikimedia.org","K9U43044RY432050M","Monthly donation to the Wikimedia Foundation","","I-R5C3YUS3285L","","-2.00","" +"10/19/2019","03:02:12","PDT","","Bank Deposit to PP Account ","Pending","USD","2.00","0.00","2.00","","simon@joyful.com","3XJ107139A851061F","","","K9U43044RY432050M","","0.00","" +"10/22/2019","05:07:06","PDT","Noble Benefactor","Subscription Payment","Completed","USD","10.00","-0.59","9.41","noble@bene.fac.tor","simon@joyful.com","6L8L1662YP1334033","Joyful Systems","","I-KC9VBGY2GWDB","","9.41","" + +# paypal-custom.csv.rules + +# Tips: +# Export from Activity -> Statements -> Custom -> Activity download +# Suggested transaction type: "Balance affecting" +# Paypal's default fields in 2018 were: +# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Shipping Address","Address Status","Item Title","Item ID","Shipping and Handling Amount","Insurance Amount","Sales Tax","Option 1 Name","Option 1 Value","Option 2 Name","Option 2 Value","Reference Txn ID","Invoice Number","Custom Number","Quantity","Receipt ID","Balance","Address Line 1","Address Line 2/District/Neighborhood","Town/City","State/Province/Region/County/Territory/Prefecture/Republic","Zip/Postal Code","Country","Contact Phone Number","Subject","Note","Country Code","Balance Impact" +# This rules file assumes the following more detailed fields, configured in "Customize report fields": +# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note" + +fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note + +skip 1 + +date-format %-m/%-d/%Y + +# ignore some paypal events +if +In Progress +Temporary Hold +Update to + skip + +# add more fields to the description +description %description_ %itemtitle + +# save some other fields as tags +comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_ + +# convert to short currency symbols +if %currency USD + currency $ +if %currency EUR + currency E +if %currency GBP + currency P + +# generate postings + +# the first posting will be the money leaving/entering my paypal account +# (negative means leaving my account, in all amount fields) +account1 assets:online:paypal +amount1 %netamount + +# the second posting will be money sent to/received from other party +# (account2 is set below) +amount2 -%grossamount + +# if there's a fee, add a third posting for the money taken by paypal. +if %feeamount [1-9] + account3 expenses:banking:paypal + amount3 -%feeamount + comment3 business: + +# choose an account for the second posting + +# override the default account names: +# if the amount is positive, it's income (a debit) +if %grossamount ^[^-] + account2 income:unknown +# if negative, it's an expense (a credit) +if %grossamount ^- + account2 expenses:unknown + +# apply common rules for setting account2 & other tweaks +include common.rules + +# apply some overrides specific to this csv + +# Transfers from/to bank. These are usually marked Pending, +# which can be disregarded in this case. +if +Bank Account +Bank Deposit to PP Account + description %type for %referencetxnid %itemtitle + account2 assets:bank:wf:pchecking + account1 assets:online:paypal + +# Currency conversions +if Currency Conversion + account2 equity:currency conversion + +# common.rules + +if +darcs +noble benefactor + account2 revenues:foss donations:darcshub + comment2 business: + +if +Calm Radio + account2 expenses:online:apps + +if +electronic frontier foundation +Patreon +wikimedia +Advent of Code + account2 expenses:dues + +if Google + account2 expenses:online:apps + description google | music + +$ hledger -f paypal-custom.csv print +2019-10-01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed + assets:online:paypal $-6.99 = $-6.99 + expenses:online:apps $6.99 + +2019-10-01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending + assets:online:paypal $6.99 = $0.00 + assets:bank:wf:pchecking $-6.99 + +2019-10-01 (2722394R5F586712G) Patreon Patreon* Membership ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed + assets:online:paypal $-7.00 = $-7.00 + expenses:dues $7.00 + +2019-10-01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending + assets:online:paypal $7.00 = $0.00 + assets:bank:wf:pchecking $-7.00 + +2019-10-19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed + assets:online:paypal $-2.00 = $-2.00 + expenses:dues $2.00 + expenses:banking:paypal ; business: + +2019-10-19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending + assets:online:paypal $2.00 = $0.00 + assets:bank:wf:pchecking $-2.00 + +2019-10-22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed + assets:online:paypal $9.41 = $9.41 + revenues:foss donations:darcshub $-10.00 ; business: + expenses:banking:paypal $0.59 ; business: + + +File: hledger.info, Node: Timeclock, Next: Timedot, Prev: CSV, Up: Top + +10 Timeclock +************ + +hledger can read time logs in the timeclock time logging format of +timeclock.el. As with Ledger, hledger's timeclock format is a +subset/variant of timeclock.el's. + + hledger's timeclock format was updated in hledger 1.43 and 1.50. If +your old time logs are rejected, you should adapt them to modern +hledger; for now, you can restore the pre-1.43 behaviour with the +'--old-timeclock' flag. + + Here the timeclock format in hledger 1.50+: + +# Comment lines like these, and blank lines, are ignored: +# comment line +; comment line +* comment line + +# Lines beginning with b, h, or capital O are also ignored, for compatibility: +b SIMPLEDATE HH:MM[:SS][+-ZZZZ][ TEXT] +h SIMPLEDATE HH:MM[:SS][+-ZZZZ][ TEXT] +O SIMPLEDATE HH:MM[:SS][+-ZZZZ][ TEXT] + +# Lines beginning with i or o are are clock-in / clock-out entries: +i SIMPLEDATE HH:MM[:SS][+-ZZZZ] ACCOUNT[ DESCRIPTION][;COMMENT]] +o SIMPLEDATE HH:MM[:SS][+-ZZZZ][ ACCOUNT][;COMMENT] + + The date is a hledger simple date (YYYY-MM-DD or similar). The time +parts must use two digits. The seconds are optional. A + or - +four-digit time zone is accepted for compatibility, but currently +ignored; times are always interpreted as a local time. + + In clock-in entries ('i'), the account name is required. A +transaction description, separated from the account name by 2+ spaces, +is optional. A transaction comment, beginning with ';', is also +optional. (Indented following comment lines are also allowed, as in +journal format.) + + In clock-out entries ('o') have no description, but can have a +comment if you wish. A clock-in and clock-out pair form a "transaction" +posting some number of hours to an account - also known as a session. +Eg: + +i 2015/03/30 09:00:00 session1 +o 2015/03/30 10:00:00 + +$ hledger -f a.timeclock print +2015-03-30 * 09:00-10:00 + (session1) 1.00h + + Clock-ins and clock-outs are matched by their account/session name. +If a clock-out does not specify a name, the most recent unclosed +clock-in is closed. You can have multiple sessions active +simultaneously. Entries are processed in the order they are parsed. +Sessions spanning more than one day are automatically split at day +boundaries. + + Eg, the following time log: + +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 +i 2015/04/02 12:00:00 another:account ; this demonstrates multple sessions being clocked in +i 2015/04/02 13:00:00 some account +o 2015/04/02 14:00:00 +o 2015/04/02 15:00:00 another:account + + generates these transactions: + +$ 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 + +2015-04-02 * 12:00-15:00 ; this demonstrates multiple sessions being clocked in + (another:account) 3.00h + +2015-04-02 * 13:00-14:00 + (some account) 1.00h + + Here is a sample.timeclock to download and some queries to try: + +$ hledger -f sample.timeclock balance # current time balances +$ hledger -f sample.timeclock register -p 2009/3 # sessions in march 2009 +$ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week + + To generate time logs, ie to clock in and clock out, you could: + + * use these shell aliases at the command line: + + alias ti='echo i `date "+%Y-%m-%d %H:%M:%S"` $* >>$TIMELOG' + alias to='echo o `date "+%Y-%m-%d %H:%M:%S"` >>$TIMELOG' + + * or Emacs's built-in timeclock.el, or the extended timeclock-x.el, + and perhaps the extras in ledgerutils.el + + * or use the old 'ti' and 'to' scripts in the ledger 2.x repository. + These rely on a "timeclock" executable which I think is just the + ledger 2 executable renamed. + + +File: hledger.info, Node: Timedot, Next: PART 3 REPORTING CONCEPTS, Prev: Timeclock, Up: Top + +11 Timedot +********** + +'timedot' format is hledger's human-friendly time logging format. +Compared to 'timeclock' format, it is more convenient for quick, +approximate, and retroactive time logging, and more human-readable (you +can see at a glance where time was spent). A quick example: + +2023-05-01 +hom:errands .... .... ; two hours; the space is ignored +fos:hledger:timedot .. ; half an hour +per:admin:finance ; no time spent yet + + hledger reads this as a transaction on this day with three +(unbalanced) postings, where each dot represents "0.25". No commodity +symbol is assumed, but we typically interpret it as hours. + +$ hledger -f a.timedot print # .timedot file extension (or timedot: prefix) is required +2023-05-01 * + (hom:errands) 2.00 ; two hours + (fos:hledger:timedot) 0.50 ; half an hour + (per:admin:finance) 0 + + A timedot file contains a series of transactions (usually one per +day). Each begins with a *simple date* (Y-M-D, Y/M/D, or Y.M.D), +optionally be followed on the same line by a transaction description, +and/or a transaction comment following a semicolon. + + After the date line are zero or more time postings, consisting of: + + * *An account name* - any hledger-style account name, optionally + indented. + + * *Two or more spaces* - required if there is an amount (as in + journal format). + + * *A timedot amount*, which can be + + * empty (representing zero) + + * a number, optionally followed by a unit 's', 'm', 'h', 'd', + 'w', 'mo', or 'y', representing a precise number of seconds, + minutes, hours, days weeks, months or years (hours is assumed + by default), which will be converted to hours according to 60s + = 1m, 60m = 1h, 24h = 1d, 7d = 1w, 30d = 1mo, 365d = 1y. + + * one or more dots (period characters), each representing 0.25. + These are the dots in "timedot". Spaces are ignored and can + be used for grouping/alignment. + + * _Added in 1.32_ one or more letters. These are like dots but + they also generate a tag 't:' (short for "type") with the + letter as its value, and a separate posting for each of the + values. This provides a second dimension of categorisation, + viewable in reports with '--pivot t'. + + * *An optional comment* following a semicolon (a hledger-style + posting comment). + + There is some flexibility to help with keeping time log data and +notes in the same file: + + * Blank lines and lines beginning with '#' or ';' are ignored. + + * After the first date line, lines which do not contain a double + space are parsed as postings with zero amount. (hledger's register + reports will show these if you add -E). + + * Before the first date line, lines beginning with '*' (eg org + headings) are ignored. And from the first date line onward, Emacs + org mode heading prefixes at the start of lines (one or more '*''s + followed by a space) will be ignored. This means the time log can + also be a org outline. + + Timedot files don't support directives like journal files. So a +common pattern is to have a main journal file (eg 'time.journal') that +contains any needed directives, and then includes the timedot file +('include time.timedot'). + +* Menu: + +* Timedot examples:: + + +File: hledger.info, Node: Timedot examples, Up: Timedot + +11.1 Timedot examples +===================== + +Numbers: + +2016/2/3 +inc:client1 4 +fos:hledger 3h +biz:research 60m + + Dots: + +# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc. +2016/2/1 +inc:client1 .... .... .... .... .... .... +fos:haskell .... .. +biz:research . + +2016/2/2 +inc:client1 .... .... +biz:research . + +$ hledger -f a.timedot print date:2016/2/2 +2016-02-02 * + (inc:client1) 2.00 + +2016-02-02 * + (biz:research) 0.25 + +$ hledger -f a.timedot bal --daily --tree +Balance changes in 2016-02-01-2016-02-03: + + || 2016-02-01d 2016-02-02d 2016-02-03d +============++======================================== + biz || 0.25 0.25 1.00 + research || 0.25 0.25 1.00 + fos || 1.50 0 3.00 + haskell || 1.50 0 0 + hledger || 0 0 3.00 + inc || 6.00 2.00 4.00 + client1 || 6.00 2.00 4.00 +------------++---------------------------------------- + || 7.75 2.25 8.00 + + Letters: + +# Activity types: +# c cleanup/catchup/repair +# e enhancement +# s support +# l learning/research + +2023-11-01 +work:adm ccecces + +$ hledger -f a.timedot print +2023-11-01 + (work:adm) 1 ; t:c + (work:adm) 0.5 ; t:e + (work:adm) 0.25 ; t:s + +$ hledger -f a.timedot bal + 1.75 work:adm +-------------------- + 1.75 + +$ hledger -f a.timedot bal --pivot t + 1.00 c + 0.50 e + 0.25 s +-------------------- + 1.75 + + Org: + +* 2023 Work Diary +** Q1 +*** 2023-02-29 +**** DONE +0700 yoga +**** UNPLANNED +**** BEGUN +hom:chores + cleaning ... + water plants + outdoor - one full watering can + indoor - light watering +**** TODO +adm:planning: trip +*** LATER + + Using '.' as account name separator: + +2016/2/4 +fos.hledger.timedot 4h +fos.ledger .. + +$ hledger -f a.timedot --alias '/\./=:' bal -t + 4.50 fos + 4.00 hledger:timedot + 0.50 ledger +-------------------- + 4.50 + + +File: hledger.info, Node: PART 3 REPORTING CONCEPTS, Next: Time periods, Prev: Timedot, Up: Top + +12 PART 3: REPORTING CONCEPTS +***************************** + + +File: hledger.info, Node: Time periods, Next: Depth, Prev: PART 3 REPORTING CONCEPTS, Up: Top + +13 Time periods +*************** + +* Menu: + +* Report start & end date:: +* Smart dates:: +* Report intervals:: +* Date adjustments:: +* Period headings:: +* Period expressions:: + + +File: hledger.info, Node: Report start & end date, Next: Smart dates, Up: Time periods + +13.1 Report start & end date +============================ + +Most hledger reports will by default show the full time period +represented by the journal. The report start date will be the earliest +transaction or posting date, and the report end date will be the latest +transaction, posting, or market price date. + + Often you will want to see a shorter period, such as the current +month. You can specify a start and/or end date with the '-b/--begin', +'-e/--end', or '-p/--period' options, or a 'date:' query argument, +described below. All of these accept the smart date syntax, also +described below. + + End dates are exclusive; specify the day after the last day you want +to see in the report. + + When dates are specified by multiple options, the last (right-most) +option wins. And when 'date:' queries and date options are combined, +the report period will be their intersection. + + Examples: + +'-b 2016/3/17' + + beginning on St. Patrick's day 2016 +'-e 12/1' + + ending at the start of December 1st in the current year +'-p 'this month'' + + during the current month +'-p thismonth' + + same as above, spaces are optional +'-b 2023' + + beginning on the first day of 2023 +'date:2023..' or 'date:2023-' + + same as above + + '-b 2024 -e 2025 -p '2000 to 2030' date:2020-01 date:2020' : +during January 2020 (the smallest common period, with the -p overriding +-b and -e) + + +File: hledger.info, Node: Smart dates, Next: Report intervals, Prev: Report start & end date, Up: Time periods + +13.2 Smart dates +================ + +In hledger's user interfaces (though not in the journal file), you can +optionally use "smart date" syntax. Smart dates can be written with +english words, can be relative, and can have parts omitted. Missing +parts are inferred as 1, when needed. Smart dates can be interpreted as +dates or periods depending on the context. + + Examples: + + '2004-01-01', '2004/10/1', '2004.9.1', '20240504', '2024Q1' : +Exact dates. The year must have at least four digits, the month must be +1-12, the day must be 1-31, the separator can be '-' or '/' or '.' or +nothing. The q can be upper or lower case and the quarter number must +be 1-4. + +'2004-10' + + start of month +'2004q3' + + start of third quarter of 2004 +'q3' + + start of third quarter of current year +'2004' + + start of year +'10/1' or 'oct' or 'october' + + October 1st in current year +'21' + + 21st day in current month +'yesterday, today, tomorrow' + + -1, 0, 1 days from today +'last/this/next day/week/month/quarter/year' + + -1, 0, 1 periods from the current period +'in n days/weeks/months/quarters/years' + + n periods from the current period +'n days/weeks/months/quarters/years ahead' + + n periods from the current period +'n days/weeks/months/quarters/years ago' + + -n periods from the current period +'20181201' + + 8 digit YYYYMMDD with valid year month and day +'201812' + + 6 digit YYYYMM with valid year and month + + Dates with no separators are allowed but might give surprising +results if mistyped: + + * '20181301' (YYYYMMDD with an invalid month) is parsed as an + eight-digit year + * '20181232' (YYYYMMDD with an invalid day) gives a parse error + * '201801012' (a valid YYYYMMDD followed by additional digits) gives + a parse error + + The meaning of relative dates depends on today's date. If you need +to test or reproduce old reports, you can use the '--today' option to +override that. (Except for periodic transaction rules, which are not +affected by '--today'.) + + +File: hledger.info, Node: Report intervals, Next: Date adjustments, Prev: Smart dates, Up: Time periods + +13.3 Report intervals +===================== + +A report interval can be specified so that reports like register, +balance or activity become multi-period, showing each subperiod as a +separate row or column. + + The following standard intervals can be enabled with command-line +flags: + + * '-D/--daily' + * '-W/--weekly' + * '-M/--monthly' + * '-Q/--quarterly' + * '-Y/--yearly' + + More complex intervals can be specified using '-p/--period', +described below. + + +File: hledger.info, Node: Date adjustments, Next: Period headings, Prev: Report intervals, Up: Time periods + +13.4 Date adjustments +===================== + +* Menu: + +* Start date adjustment:: +* End date adjustment:: + + +File: hledger.info, Node: Start date adjustment, Next: End date adjustment, Up: Date adjustments + +13.4.1 Start date adjustment +---------------------------- + +If you let hledger infer a report's start date, it will adjust the date +to the previous natural boundary of the report interval, for convenient +periodic reports. (If you don't want that, specify a start date.) + + For example, if the journal's first transaction is on january 10th, + + * 'hledger register' (no report interval) will start the report on + january 10th. + * 'hledger register --monthly' will start the report on the previous + month boundary, january 1st. + * 'hledger register --monthly --begin 1/5' will start the report on + january 5th [1]. + + Also if you are generating transactions or budget goals with periodic +transaction rules, their start date may be adjusted in a similar way (in +certain situations). + + +File: hledger.info, Node: End date adjustment, Prev: Start date adjustment, Up: Date adjustments + +13.4.2 End date adjustment +-------------------------- + +A report's end date is always adjusted to include a whole number of +intervals, so that the last subperiod has the same length as the others. + + For example, if the journal's last transaction is on february 20th, + + * 'hledger register' will end the report on february 20th. + * 'hledger register --monthly' will end the report at the end of + february. + * 'hledger register --monthly --end 2/14' also will end the report at + the end of february (overriding the requested end date). + * 'hledger register --monthly --begin 1/5 --end 2/14' will end the + report on march 4th [1]. + + [1] Since hledger 1.29. + + +File: hledger.info, Node: Period headings, Next: Period expressions, Prev: Date adjustments, Up: Time periods + +13.5 Period headings +==================== + +With non-standard subperiods, hledger will show "STARTDATE..ENDDATE" +headings. With standard subperiods (ie, starting on a natural interval +boundary), you'll see more compact headings, which are usually +preferable. (Though month names will be in english, currently.) + + So if you are specifying a start date and you want compact headings: +choose a start of year for yearly reports, a start of quarter for +quarterly reports, a start of month for monthly reports, etc. +(Remember, you can write eg '-b 2024' or '1/1' as a shortcut for a start +of year, or '2024-04' or '202404' or 'Apr' for a start of month or +quarter.) + + For weekly reports, choose a date that's a Monday. (You can try +different dates until you see the short headings, or write eg '-b '3 +weeks ago''.) + + +File: hledger.info, Node: Period expressions, Prev: Period headings, Up: Time periods + +13.6 Period expressions +======================= + +The '-p/--period' option specifies a period expression, which is a +compact way of expressing a start date, end date, and/or report +interval. + + Here's a period expression with a start and end date (specifying the +first quarter of 2009): + +'-p "from 2009/1/1 to 2009/4/1"' + + Several keywords like "from" and "to" are supported for readability; +these are optional. "to" can also be written as ".." or "-". The +spaces are also optional, as long as you don't run two dates together. +So the following are equivalent to the above: + +'-p "2009/1/1 2009/4/1"' +'-p2009/1/1to2009/4/1' +'-p2009/1/1..2009/4/1' + + Dates are smart dates, so if the current year is 2009, these are also +equivalent to the above: + +'-p "1/1 4/1"' +'-p "jan-apr"' +'-p "this year to 4/1"' + + If you specify only one date, the missing start or end date will be +the earliest or latest transaction date in the journal: + +'-p "from 2009/1/1"' everything after january 1, 2009 +'-p "since 2009/1"' the same, since is a synonym +'-p "from 2009"' the same +'-p "to 2009"' everything before january 1, 2009 + + You can also specify a period by writing a single partial or full +date: + +'-p "2009"' the year 2009; equivalent to “2009/1/1 to 2010/1/1” +'-p "2009/1"' the month of january 2009; equivalent to “2009/1/1 to + 2009/2/1” +'-p the first day of 2009; equivalent to “2009/1/1 to +"2009/1/1"' 2009/1/2” + + or by using the "Q" quarter-year syntax (case insensitive): + +'-p "2009Q1"' first quarter of 2009, equivalent to “2009/1/1 to + 2009/4/1” +'-p "q4"' fourth quarter of the current year + +* Menu: + +* Period expressions with a report interval:: +* More complex report intervals:: +* Multiple weekday intervals:: + + +File: hledger.info, Node: Period expressions with a report interval, Next: More complex report intervals, Up: Period expressions + +13.6.1 Period expressions with a report interval +------------------------------------------------ + +A period expression can also begin with a report interval, separated +from the start/end dates (if any) by a space or the word 'in': + +'-p "weekly from 2009/1/1 to 2009/4/1"' +'-p "monthly in 2008"' +'-p "quarterly"' + + +File: hledger.info, Node: More complex report intervals, Next: Multiple weekday intervals, Prev: Period expressions with a report interval, Up: Period expressions + +13.6.2 More complex report intervals +------------------------------------ + +Some more complex intervals can be specified within period expressions, +such as: + + * 'biweekly' (every two weeks) + * 'fortnightly' + * 'bimonthly' (every two months) + * 'every day|week|month|quarter|year' + * 'every N days|weeks|months|quarters|years' + + Weekly on a custom day: + + * 'every Nth day of week' ('th', 'nd', 'rd', or 'st' are all accepted + after the number) + * 'every WEEKDAYNAME' (full or three-letter english weekday name, + case insensitive) + + Monthly on a custom day: + + * 'every Nth day [of month]' ('31st day' will be adjusted to each + month's last day) + * 'every Nth WEEKDAYNAME [of month]' + + Yearly on a custom month and day: + + * 'every MM/DD [of year]' (month number and day of month number) + * 'every MONTHNAME DDth [of year]' (full or three-letter english + month name, case insensitive, and day of month number) + * 'every DDth MONTHNAME [of year]' (equivalent to the above) + + Examples: + +'-p "bimonthly from +2008"' +'-p "every 2 weeks"' +'-p "every 5 months from +2009/03"' +'-p "every 2nd day of periods will go from Tue to Tue +week"' +'-p "every Tue"' same +'-p "every 15th day"' period boundaries will be on 15th of each + month +'-p "every 2nd Monday"' period boundaries will be on second Monday + of each month +'-p "every 11/05"' yearly periods with boundaries on 5th of + November +'-p "every 5th November"' same +'-p "every Nov 5th"' same + + Show historical balances at end of the 15th day of each month (N is +an end date, exclusive as always): + +$ hledger balance -H -p "every 16th day" + + Group postings from the start of wednesday to end of the following +tuesday (N is both (inclusive) start date and (exclusive) end date): + +$ hledger register checking -p "every 3rd day of week" + + +File: hledger.info, Node: Multiple weekday intervals, Prev: More complex report intervals, Up: Period expressions + +13.6.3 Multiple weekday intervals +--------------------------------- + +This special form is also supported: + + * 'every WEEKDAYNAME,WEEKDAYNAME,...' (full or three-letter english + weekday names, case insensitive) + + Also, 'weekday' and 'weekendday' are shorthand for +'mon,tue,wed,thu,fri' and 'sat,sun'. + + This is mainly intended for use with '--forecast', to generate +periodic transactions on arbitrary days of the week. It may be less +useful with '-p', since it divides each week into subperiods of unequal +length, which is unusual. (Related: #1632) + + Examples: + +'-p "every dates will be Mon, Wed, Fri; periods will be +mon,wed,fri"' Mon-Tue, Wed-Thu, Fri-Sun +'-p "every dates will be Mon, Tue, Wed, Thu, Fri; periods will +weekday"' be Mon, Tue, Wed, Thu, Fri-Sun +'-p "every dates will be Sat, Sun; periods will be Sat, Sun-Fri +weekendday"' + + +File: hledger.info, Node: Depth, Next: Queries, Prev: Time periods, Up: Top + +14 Depth +******** + +With the '--depth NUM' option (short form, usually preferred: '-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. So all of these +are equivalent: 'depth:2', '--depth=2', '-2'. + + You can also provide custom depths for specific accounts, by +providing a 'REGEX=NUM' argument instead of just 'NUM' _(since 1.41)_. +For example, '--depth assets=2' (or 'depth:assets=2') will collapse +accounts matching the regular expression "assets" to depth 2. So +'assets:bank:savings' would be collapsed to 'assets:bank', but +'liabilities:bank:credit card' would not be affected. + + If REGEX contains spaces or other special characters, enclose it in +quotes in the usual way. Eg: '--depth 'credit card=2'' + +* Menu: + +* Combining depth options:: + + +File: hledger.info, Node: Combining depth options, Up: Depth + +14.1 Combining depth options +============================ + +If a command line contains multiple general depth options, the last one +wins. (Useful for overriding a depth specified by scripts.) + + Or a command may contain a combination of general and custom depth +options. In this case, the most specifically (deepest) matching option +wins. Some examples: + + * '--depth assets=3 --depth expenses=2 --depth 1' would collapse + accounts containing "assets" to depth 3, accounts containing + "expenses" to depth 2, and all other accounts to depth 1. + + * '--depth assets=1 --depth savings=2' would collapse + 'assets:bank:savings' to depth 2 (not depth 1; because "savings" + matches a deeper part of the account name than "assets"). + + Note currently, to override a custom depth option '--depth REGEX=NUM' +with a later option, the later option must use the same REGEX. + + +File: hledger.info, Node: Queries, Next: Pivoting, Prev: Depth, Up: Top + +15 Queries +********** + +Many hledger commands accept query arguments, which restrict their scope +and let you report on a precise subset of your data. Here's a quick +overview of hledger's queries: + + * By default, a query argument is treated as a case-insensitive + substring pattern for matching account names. Eg: + + 'dining groceries' + 'car:fuel' + + * Patterns containing spaces or other special characters must be + enclosed in single or double quotes: + + ''personal care'' + + * Patterns are actually regular expressions, so you can add regexp + metacharacters for more precision (or you may need to + backslash-escape certain characters; see "Regular expressions" + above): + + ''^expenses\b'' + ''food$'' + ''fuel|repair'' + ''accounts (payable|receivable)'' + + * To match something other than the account name, you can add a query + type prefix, such as: + + 'date:202312-' + 'status:' + 'desc:amazon' + 'cur:USD' + 'cur:\\$' + 'amt:'>0'' + 'acct:groceries' (but 'acct:' is the default, so we usually don't + bother writing it) + + * To negate a query, add a 'not:' prefix: + + 'not:status:'*'' + 'not:desc:'opening|closing'' + 'not:cur:USD' + + * Multiple query terms can be combined, as space-separated queries + Eg: 'hledger print date:2022 desc:amazon desc:amzn' (show + transactions dated in 2022 whose description contains "amazon" or + "amzn"). + + * Or more flexibly as boolean queries. Eg: 'hledger print + expr:'date:2022 and (desc:amazon or desc:amzn) and not + date:202210'' + + All hledger commands use the same query language, but different +commands may interpret the query in different ways. We haven't +described the commands yet (that's coming in PART 4: COMMANDS below) but +here's the gist of it: + + * Transaction-oriented commands ('print', 'aregister', 'close', + 'import', 'descriptions'..) try to match transactions (including + the transaction's postings). + + * Posting-oriented commands ('register', 'balance', 'balancesheet', + 'incomestatement', 'accounts'..) try to match postings. Postings + inherit their transaction's attributes for querying purposes, so + transaction fields like date or description can still be referenced + in a posting query. + + * A few commands match in more specific ways. (Eg 'aregister', which + has a special first argument.) + +* Menu: + +* Query types:: +* Negative queries:: +* Space-separated queries:: +* Boolean queries:: +* Queries and command options:: +* Queries and account aliases:: +* Queries and valuation:: + + +File: hledger.info, Node: Query types, Next: Negative queries, Up: Queries + +15.1 Query types +================ + +Here are the query types available: + +* Menu: + +* acct query:: +* amt query:: +* code query:: +* cur query:: +* desc query:: +* date query:: +* date2 query:: +* depth query:: +* note query:: +* payee query:: +* real query:: +* status query:: +* type query:: +* tag query:: + + +File: hledger.info, Node: acct query, Next: amt query, Up: Query types + +15.1.1 acct: query +------------------ + +*'acct:REGEX'*, or just *'REGEX'* +Match account names containing this case insensitive regular expression. +This is the default query type, so we usually don't bother writing the +"acct:" prefix. + + +File: hledger.info, Node: amt query, Next: code query, Prev: acct query, Up: Query types + +15.1.2 amt: query +----------------- + +*'amt:N, amt:'N', amt:'>=N''* +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.) 'amt:' needs quotes to hide the less +than/greater than sign from the command line shell. + + 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. + + Keep in mind that 'amt:' matches posting amounts, not account +balances. + + +File: hledger.info, Node: code query, Next: cur query, Prev: amt query, Up: Query types + +15.1.3 code: query +------------------ + +*'code:REGEX'* +Match by transaction code (eg check number). + + +File: hledger.info, Node: cur query, Next: desc query, Prev: code query, Up: Query types + +15.1.4 cur: query +----------------- + +*'cur:REGEX'* +Match postings or transactions including any amounts whose +currency/commodity symbol is fully matched by REGEX. (Contrary to +hledger's usual infix matching. To do infix matching, write +'.*REGEX.*'.) Note, to match special characters which are +regex-significant, you need to escape them with '\'. And for characters +which are significant to your shell you will usually need one more level +of escaping. Eg to match the dollar sign: 'cur:\\$' or 'cur:'\$'' + + +File: hledger.info, Node: desc query, Next: date query, Prev: cur query, Up: Query types + +15.1.5 desc: query +------------------ + +*'desc:REGEX'* +Match transaction descriptions. + + +File: hledger.info, Node: date query, Next: date2 query, Prev: desc query, Up: Query types + +15.1.6 date: query +------------------ + +*'date:PERIODEXPR'* +Match dates (or with the '--date2' flag, secondary dates) within the +specified period. PERIODEXPR is a period expression with no report +interval. Examples: +'date:2016', 'date:thismonth', 'date:2/1-2/15', +'date:2021-07-27..nextquarter'. + + +File: hledger.info, Node: date2 query, Next: depth query, Prev: date query, Up: Query types + +15.1.7 date2: query +------------------- + +*'date2:PERIODEXPR'* +If you use secondary dates: this matches secondary dates within the +specified period. It is not affected by the '--date2' flag. + + +File: hledger.info, Node: depth query, Next: note query, Prev: date2 query, Up: Query types + +15.1.8 depth: query +------------------- + +*'depth:[REGEXP=]N'* +Match (or display, depending on command) accounts at or above this +depth, optionally only for accounts matching a provided regular +expression. See Depth for detailed rules. + + +File: hledger.info, Node: note query, Next: payee query, Prev: depth query, Up: Query types + +15.1.9 note: query +------------------ + +*'note:REGEX'* +Match transaction notes (the part of the description right of '|', or +the whole description if there's no '|'). + + +File: hledger.info, Node: payee query, Next: real query, Prev: note query, Up: Query types + +15.1.10 payee: query +-------------------- + +*'payee:REGEX'* +Match transaction payee/payer names (the part of the description left of +'|', or the whole description if there's no '|'). + + +File: hledger.info, Node: real query, Next: status query, Prev: payee query, Up: Query types + +15.1.11 real: query +------------------- + +*'real:, real:0'* +Match real or virtual postings respectively. + + +File: hledger.info, Node: status query, Next: type query, Prev: real query, Up: Query types + +15.1.12 status: query +--------------------- + +*'status:, status:!, status:*'* +Match unmarked, pending, or cleared transactions respectively. + + +File: hledger.info, Node: type query, Next: tag query, Prev: status query, Up: Query types + +15.1.13 type: query +------------------- + +*'type:TYPECODES'* +Match by account type (see Declaring accounts > Account types). +'TYPECODES' is one or more of the single-letter account type codes +'ALERXCV', case insensitive. Note 'type:A' and 'type:E' will also match +their respective subtypes 'C' (Cash) and 'V' (Conversion). Certain +kinds of account alias can disrupt account types, see Rewriting accounts +> Aliases and account types. + + +File: hledger.info, Node: tag query, Prev: type query, Up: Query types + +15.1.14 tag: query +------------------ + +*'tag:NAMEREGEX[=VALREGEX]'* +Match by tag name, and optionally also by tag value. Note: + + * Both regular expressions do infix matching. If you need a complete + match, use '^' and '$'. + Eg: 'tag:'^fullname$'', 'tag:'^fullname$=^fullvalue$' + * To match values, ignoring names, do 'tag:.=VALREGEX' + * Accounts also inherit the tags of their parent accounts. + * Postings also inherit the tags of their account and their + transaction . + * Transactions also acquire the tags of their postings. + + +File: hledger.info, Node: Negative queries, Next: Space-separated queries, Prev: Query types, Up: Queries + +15.2 Negative queries +===================== + +* Menu: + +* not query:: + + +File: hledger.info, Node: not query, Up: Negative queries + +15.2.1 not: query +----------------- + +*'not:QUERY'* +You can prepend *'not:'* to a query to negate the match. +Eg: 'not:equity', 'not:desc:apple' +(Also, a trick: 'not:not:...' can sometimes solve query problems +conveniently.) + + +File: hledger.info, Node: Space-separated queries, Next: Boolean queries, Prev: Negative queries, Up: Queries + +15.3 Space-separated queries +============================ + +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. + + +File: hledger.info, Node: Boolean queries, Next: Queries and command options, Prev: Space-separated queries, Up: Queries + +15.4 Boolean queries +==================== + +You can write more complicated "boolean" query expressions, enclosed in +quotes and prefixed with 'expr:'. These can combine subqueries with +NOT, AND, OR operators (case insensitive), and parentheses for grouping. +Eg, to show transactions involving both cash and expense accounts: + +hledger print expr:'cash AND expenses' + + The prefix and enclosing quotes are required, so don't write 'hledger +print cash AND expenses'. That would be a space-separated query showing +transactions involving accounts with any of "cash", "and", "expenses" in +their names. + + You can write space-separated queries _inside_ a boolean query, and +they will combine as described above, but it might be confusing and best +avoided. Eg these are equivalent, showing transactions involving cash +or expenses accounts: + +hledger print expr:'cash expenses' +hledger print cash expenses + + There is a restriction with 'date:' queries: they may not be used +inside OR expressions. + + Actually, there are three types of boolean query: 'expr:' for general +use, and 'any:' and 'all:' variants which can be useful with 'print'. + +* Menu: + +* expr query:: +* any query:: +* all query:: + + +File: hledger.info, Node: expr query, Next: any query, Up: Boolean queries + +15.4.1 expr: query +------------------ + +*'expr:'QUERYEXPR''* +For example, 'expr:'date:lastmonth AND NOT (food OR rent)'' means "match +things which are dated in the last month and do not have food or rent in +the account name". + + When using 'expr:' with transaction-oriented commands like 'print', +posting-oriented query terms like 'acct:' and 'amt:' are considered to +match the transaction if they match any of its postings. +So, 'hledger print expr:'cash and amt:>0'' means "show transactions with +(at least one posting involving a cash account) and (at least one +posting with a positive amount)". + + +File: hledger.info, Node: any query, Next: all query, Prev: expr query, Up: Boolean queries + +15.4.2 any: query +----------------- + +*'any:'QUERYEXPR''* +Like 'expr:', but when used with transaction-oriented commands like +'print', it matches the transaction only if a posting can be matched by +all of QUERYEXPR. +So, 'hledger print any:'cash and amt:>0'' means "show transactions where +at least one posting posts a positive amount to a cash account". + + +File: hledger.info, Node: all query, Prev: any query, Up: Boolean queries + +15.4.3 all: query +----------------- + +*'all:'QUERYEXPR''* +Like 'expr:', but when used with transaction-oriented commands like +'print', it matches the transaction only if all postings are matched by +all of QUERYEXPR (and there is at least one posting). +So, 'hledger print all:'cash and amt:0'' means "show transactions where +all postings involve a cash account and have a zero amount". +Or, 'hledger print all:'cash or checking'' means "show transactions +which touch only cash and/or checking accounts". + + +File: hledger.info, Node: Queries and command options, Next: Queries and account aliases, Prev: Boolean queries, Up: Queries + +15.5 Queries and command options +================================ + +Some queries can also be expressed as command-line options: 'depth:2' is +equivalent to '--depth 2', 'date:2023' is equivalent to '-p 2023', etc. +When you mix command options and query arguments, generally the +resulting query is their intersection. + + +File: hledger.info, Node: Queries and account aliases, Next: Queries and valuation, Prev: Queries and command options, Up: Queries + +15.6 Queries and account aliases +================================ + +When account names are rewritten with '--alias' or 'alias', 'acct:' will +match either the old or the new account name. + + +File: hledger.info, Node: Queries and valuation, Prev: Queries and account aliases, Up: Queries + +15.7 Queries and valuation +========================== + +When amounts are converted to other commodities in cost or value +reports, 'cur:' and 'amt:' match the old commodity symbol and the old +amount quantity, not the new ones. (Except in hledger 1.22, #1625.) + + +File: hledger.info, Node: Pivoting, Next: Generating data, Prev: Queries, Up: Top + +16 Pivoting +*********** + +Normally, hledger groups amounts and displays their totals by account +(name). With '--pivot PIVOTEXPR', some other field's (or multiple +fields') value is used as a synthetic account name, causing different +grouping and display. PIVOTEXPR can be + + * any of these standard transaction or posting fields (their value is + substituted): 'status', 'code', 'desc', 'payee', 'note', 'acct', + 'comm'/'cur', 'amt', 'cost' + * or a tag name + * or any combination of these, colon-separated. + + Some special cases: + + * Colons appearing in PIVOTEXPR or in a pivoted tag value will + generate account hierarchy. + * When pivoting a posting has multiple values for a tag, the pivoted + value of that tag will be the first value. + * When a posting has multiple commodities, the pivoted value of + "comm"/"cur" will be "". Also when an unrecognised tag name or + field is provided, its pivoted value will be "". (If this causes + confusing output, consider excluding those postings from the + report.) + + Examples: + +2016/02/16 Yearly Dues Payment + assets:bank account 2 EUR + income:dues -2 EUR ; member: John Doe, kind: Lifetime + + Normal balance report showing account names: + +$ hledger balance + 2 EUR assets:bank account + -2 EUR income:dues +-------------------- + 0 + + Pivoted balance report, using member: tag values instead: + +$ hledger balance --pivot member + 2 EUR + -2 EUR John Doe +-------------------- + 0 + + One way to show only amounts with a member: value (using a query): + +$ hledger balance --pivot member tag:member=. + -2 EUR John Doe +-------------------- + -2 EUR + + Another way (the acct: query matches against the pivoted "account +name"): + +$ hledger balance --pivot member acct:. + -2 EUR John Doe +-------------------- + -2 EUR + + Hierarchical reports can be generated with multiple pivot values: + +$ hledger balance Income:Dues --pivot kind:member + -2 EUR Lifetime:John Doe +-------------------- + -2 EUR + + +File: hledger.info, Node: Generating data, Next: Forecasting, Prev: Pivoting, Up: Top + +17 Generating data +****************** + +hledger can enrich the data provided to it, or generate new data, in a +number of ways. Mostly, this is done only if you request it: + + * Missing amounts or missing costs in transactions are inferred + automatically when possible. + * The '--infer-equity' flag infers missing conversion equity postings + from @/@@ costs. + * The '--infer-costs' flag infers missing costs from conversion + equity postings. + * The '--infer-market-prices' flag infers 'P' price directives from + costs. + * The '--auto' flag adds extra postings to transactions matched by + auto posting rules. + * The '--forecast' option generates transactions from periodic + transaction rules. + * The 'balance --budget' report infers budget goals from periodic + transaction rules. + * Commands like 'close', 'rewrite', and 'hledger-interest' generate + transactions or postings. + * CSV data is converted to transactions by applying CSV conversion + rules.. etc. + + Such generated data is temporary, existing only at report time. You +can convert it to permanent recorded data by, eg, capturing the output +of 'hledger print' and saving it in your journal file. This can +sometimes be useful as a data entry aid. + + If you are curious what data is being generated and why, run 'hledger +print -x --verbose-tags'. '-x/--explicit' shows inferred amounts and +'--verbose-tags' adds tags like 'generated-transaction' (from periodic +rules) and 'generated-posting', 'modified' (from auto posting rules). +Similar hidden tags (with an underscore prefix) are always present, +also, so you can always match such data with queries like +'tag:generated' or 'tag:modified'. + + +File: hledger.info, Node: Forecasting, Next: Budgeting, Prev: Generating data, Up: Top + +18 Forecasting +************** + +Forecasting, or speculative future reporting, can be useful for +estimating future balances, or for exploring different future scenarios. + + The simplest and most flexible way to do it with hledger is to +manually record a bunch of future-dated transactions. You could keep +these in a separate 'future.journal' and include that with '-f' only +when you want to see them. + +* Menu: + +* --forecast:: +* Inspecting forecast transactions:: +* Forecast reports:: +* Forecast tags:: +* Forecast period in detail:: +* Forecast troubleshooting:: + + +File: hledger.info, Node: --forecast, Next: Inspecting forecast transactions, Up: Forecasting + +18.1 -forecast +============== + +There is another way: with the '--forecast' option, hledger can generate +temporary "forecast transactions" for reporting purposes, according to +periodic transaction rules defined in the journal. Each rule can +generate multiple recurring transactions, so by changing one rule you +can change many forecasted transactions. + + Forecast transactions usually start after ordinary transactions end. +By default, they begin after your latest-dated ordinary transaction, or +today, whichever is later, and they end six months from today. (The +exact rules are a little more complicated, and are given below.) + + This is the "forecast period", which need not be the same as the +report period. You can override it - eg to forecast farther into the +future, or to force forecast transactions to overlap your ordinary +transactions - by giving the -forecast option a period expression +argument, like '--forecast=..2099' or '--forecast=2023-02-15..'. Note +that the '=' is required. + + +File: hledger.info, Node: Inspecting forecast transactions, Next: Forecast reports, Prev: --forecast, Up: Forecasting + +18.2 Inspecting forecast transactions +===================================== + +'print' is the best command for inspecting and troubleshooting forecast +transactions. Eg: + +~ monthly from 2022-12-20 rent + assets:bank:checking + expenses:rent $1000 + +$ hledger print --forecast --today=2023/4/21 +2023-05-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + +2023-06-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + +2023-07-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + +2023-08-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + +2023-09-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + + Here there are no ordinary transactions, so the forecasted +transactions begin on the first occurrence after today's date. (You +won't normally use '--today'; it's just to make these examples +reproducible.) + + +File: hledger.info, Node: Forecast reports, Next: Forecast tags, Prev: Inspecting forecast transactions, Up: Forecasting + +18.3 Forecast reports +===================== + +Forecast transactions affect all reports, as you would expect. Eg: + +$ hledger areg rent --forecast --today=2023/4/21 +Transactions in expenses:rent and subaccounts: +2023-05-20 rent as:ba:checking $1000 $1000 +2023-06-20 rent as:ba:checking $1000 $2000 +2023-07-20 rent as:ba:checking $1000 $3000 +2023-08-20 rent as:ba:checking $1000 $4000 +2023-09-20 rent as:ba:checking $1000 $5000 + +$ hledger bal -M expenses --forecast --today=2023/4/21 +Balance changes in 2023-05-01..2023-09-30: + + || May Jun Jul Aug Sep +===============++=================================== + expenses:rent || $1000 $1000 $1000 $1000 $1000 +---------------++----------------------------------- + || $1000 $1000 $1000 $1000 $1000 + + +File: hledger.info, Node: Forecast tags, Next: Forecast period in detail, Prev: Forecast reports, Up: Forecasting + +18.4 Forecast tags +================== + +Forecast transactions generated by -forecast have a hidden tag, +'_generated-transaction'. So if you ever need to match forecast +transactions, you could use 'tag:_generated-transaction' (or just +'tag:generated') in a query. + + For troubleshooting, you can add the '--verbose-tags' flag. Then, +visible 'generated-transaction' tags will be added also, so you can view +them with the 'print' command. Their value indicates which periodic +rule was responsible. + + +File: hledger.info, Node: Forecast period in detail, Next: Forecast troubleshooting, Prev: Forecast tags, Up: Forecasting + +18.5 Forecast period, in detail +=============================== + +Forecast start/end dates are chosen so as to do something useful by +default in almost all situations, while also being flexible. Here are +(with luck) the exact rules, to help with troubleshooting: + + The forecast period starts on: + + * the later of + * the start date in the periodic transaction rule + * the start date in '--forecast''s argument + + * otherwise (if those are not available): the later of + * the report start date specified with '-b'/'-p'/'date:' + * the day after the latest ordinary transaction in the journal + + * otherwise (if none of these are available): today. + + The forecast period ends on: + + * the earlier of + * the end date in the periodic transaction rule + * the end date in '--forecast''s argument + + * otherwise: the report end date specified with '-e'/'-p'/'date:' + * otherwise: 180 days (~6 months) from today. + + +File: hledger.info, Node: Forecast troubleshooting, Prev: Forecast period in detail, Up: Forecasting + +18.6 Forecast troubleshooting +============================= + +When -forecast is not doing what you expect, one of these tips should +help: + + * Remember to use the '--forecast' option. + * Remember to have at least one periodic transaction rule in your + journal. + * Test with 'print --forecast'. + * Check for typos or too-restrictive start/end dates in your periodic + transaction rule. + * Leave at least 2 spaces between the rule's period expression and + description fields. + * Check for future-dated ordinary transactions suppressing forecasted + transactions. + * Try setting explicit report start and/or end dates with '-b', '-e', + '-p' or 'date:' + * Try adding the '-E' flag to encourage display of empty periods/zero + transactions. + * Try setting explicit forecast start and/or end dates with + '--forecast=START..END' + * Consult Forecast period, in detail, above. + * Check inside the engine: add '--debug=2' (eg). + + +File: hledger.info, Node: Budgeting, Next: Amount formatting, Prev: Forecasting, Up: Top + +19 Budgeting +************ + +With the balance command's '--budget' report, each periodic transaction +rule generates recurring budget goals in specified accounts, and goals +and actual performance can be compared. See the balance command's doc +below. + + You can generate budget goals and forecast transactions at the same +time, from the same or different periodic transaction rules: 'hledger +bal -M --budget --forecast ...' + + See also: Budgeting and Forecasting. + + +File: hledger.info, Node: Amount formatting, Next: Cost reporting, Prev: Budgeting, Up: Top + +20 Amount formatting +******************** + +* Menu: + +* Commodity display style:: +* Rounding:: +* Trailing decimal marks:: +* Amount parseability:: + + +File: hledger.info, Node: Commodity display style, Next: Rounding, Up: Amount formatting + +20.1 Commodity display style +============================ + +For the amounts in each commodity, hledger chooses a consistent display +style (symbol placement, decimal mark and digit group marks, number of +decimal digits) to use in most reports. This is inferred as follows: + + First, if there's a 'D' directive declaring a default commodity, that +commodity symbol and amount format is applied to all no-symbol amounts +in the journal. + + Then each commodity's display style is determined from its +'commodity' directive. We recommend always declaring commodities with +'commodity' directives, since they help ensure consistent display styles +and precisions, and bring other benefits such as error checking for +commodity symbols. Here's an example: + +# Set display styles (and decimal marks, for parsing, if there is no decimal-mark directive) +# for the $, EUR, INR and no-symbol commodities: +commodity $1,000.00 +commodity EUR 1.000,00 +commodity INR 9,99,99,999.00 +commodity 1 000 000.9455 + + But for convenience, if a 'commodity' directive is not present, +hledger infers a commodity's display styles from its amounts as they are +written in the journal (excluding cost amounts and amounts in periodic +transaction rules or auto posting rules). It uses + + * the symbol placement and decimal mark of the first amount seen + * the digit group marks of the first amount with digit group marks + * and the maximum number of decimal digits seen across all amounts. + + And as fallback if no applicable amounts are found, it would use a +default style, like '$1000.00' (symbol on the left with no space, period +as decimal mark, and two decimal digits). + + Finally, commodity styles can be overridden by the +'-c/--commodity-style' command line option. + + +File: hledger.info, Node: Rounding, Next: Trailing decimal marks, Prev: Commodity display style, Up: Amount formatting + +20.2 Rounding +============= + +Amounts are stored internally as decimal numbers with up to 255 decimal +places. They are displayed with their original journal precisions by +print and print-like reports, and rounded to their display precision +(the number of decimal digits specified by the commodity display style) +by other reports. When rounding, hledger uses banker's rounding (it +rounds to the nearest even digit). So eg 0.5 displayed with zero +decimal digits appears as "0". + + +File: hledger.info, Node: Trailing decimal marks, Next: Amount parseability, Prev: Rounding, Up: Amount formatting + +20.3 Trailing decimal marks +=========================== + +If you're wondering why your 'print' report sometimes shows trailing +decimal marks, with no decimal digits; it does this when showing amounts +that have digit group marks but no decimal digits, to disambiguate them +and allow them to be re-parsed reliably (see Decimal marks). Eg: + +commodity $1,000.00 + +2023-01-02 + (a) $1000 + +$ hledger print +2023-01-02 + (a) $1,000. + + If this is a problem (eg when exporting to Ledger), you can avoid it +by disabling digit group marks, eg with -c/-commodity (for each affected +commodity): + +$ hledger print -c '$1000.00' +2023-01-02 + (a) $1000 + + or by forcing print to always show decimal digits, with -round: + +$ hledger print -c '$1,000.00' --round=soft +2023-01-02 + (a) $1,000.00 + + +File: hledger.info, Node: Amount parseability, Prev: Trailing decimal marks, Up: Amount formatting + +20.4 Amount parseability +======================== + +More generally, hledger output falls into three rough categories, which +format amounts a little bit differently to suit different consumers: + + *1. "hledger-readable output" - should be readable by hledger (and +by humans)* + + * This is produced by reports that show full journal entries: + 'print', 'import', 'close', 'rewrite' etc. + * It shows amounts with their original journal precisions, which may + not be consistent from one amount to the next. + * It adds a trailing decimal mark when needed to avoid showing + ambiguous amounts. + * It can be parsed reliably (by hledger and ledger2beancount at + least, but perhaps not by Ledger..) + + *2. "human-readable output" - usually for humans* + + * This is produced by all other reports. + * It shows amounts with standard display precisions, which will be + consistent within each commodity. + * It shows ambiguous amounts unmodified. + * It can be parsed reliably in the context of a known report (when + you know decimals are consistently not being shown, you can assume + a single mark is a digit group mark). + + *3. "machine-readable output" - usually for other software* + + * This is produced by all reports when an output format like 'csv', + 'tsv', 'json', or 'sql' is selected. + * It shows amounts as 1 or 2 do, but without digit group marks. + * It can be parsed reliably (if needed, the decimal mark can be + changed with -c/-commodity-style). + + +File: hledger.info, Node: Cost reporting, Next: Value reporting, Prev: Amount formatting, Up: Top + +21 Cost reporting +***************** + +In some transactions - for example a currency conversion, or a purchase +or sale of stock - one commodity is exchanged for another. In these +transactions there is a conversion rate, also called the cost (when +buying) or selling price (when selling). (In hledger docs we just say +"cost" generically for convenience.) With the '-B/--cost' flag, hledger +can show amounts "at cost", converted to the cost's commodity. + +* Menu: + +* Recording costs:: +* Reporting at cost:: +* Equity conversion postings:: +* Inferring equity conversion postings:: +* Combining costs and equity conversion postings:: +* Requirements for detecting equity conversion postings:: +* Infer cost and equity by default ?:: + + +File: hledger.info, Node: Recording costs, Next: Reporting at cost, Up: Cost reporting + +21.1 Recording costs +==================== + +We'll explore several ways of recording transactions involving costs. +These are also summarised at hledger Cookbook > Cost notation. + + Costs can be recorded explicitly in the journal, using the '@ +UNITCOST' or '@@ TOTALCOST' notation described in Journal > Costs: + + *Variant 1* + +2022-01-01 + assets:dollars $-135 + assets:euros €100 @ $1.35 ; $1.35 per euro (unit cost) + + *Variant 2* + +2022-01-01 + assets:dollars $-135 + assets:euros €100 @@ $135 ; $135 total cost + + Typically, writing the unit cost (variant 1) is preferable; it can be +more effort, requiring more attention to decimal digits; but it reveals +the per-unit cost basis, and makes stock sales easier. + + Costs can also be left implicit, and hledger will infer the cost that +is consistent with a balanced transaction: + + *Variant 3* + +2022-01-01 + assets:dollars $-135 + assets:euros €100 + + Here, hledger will attach a '@@ €100' cost to the first amount (you +can see it with 'hledger print -x'). This form looks convenient, but +there are downsides: + + * It sacrifices some error checking. For example, if you + accidentally wrote €10 instead of €100, hledger would not be able + to detect the mistake. + + * It is sensitive to the order of postings - if they were reversed, a + different entry would be inferred and reports would be different. + + * The per-unit cost basis is not easy to read. + + So generally this kind of entry is not recommended. You can make +sure you have none of these by using '-s' (strict mode), or by running +'hledger check balanced'. + + +File: hledger.info, Node: Reporting at cost, Next: Equity conversion postings, Prev: Recording costs, Up: Cost reporting + +21.2 Reporting at cost +====================== + +Now when you add the '-B'/'--cost' flag to reports ("B" is from Ledger's +-B/-basis/-cost flag), any amounts which have been annotated with costs +will be converted to their cost's commodity (in the report output). Ie +they will be displayed "at cost" or "at sale price". + + Some things to note: + + * Costs are attached to specific posting amounts in specific + transactions, and once recorded they do not change. This contrasts + with market prices, which are ambient and fluctuating. + + * Conversion to cost is performed before conversion to market value + (described below). + + +File: hledger.info, Node: Equity conversion postings, Next: Inferring equity conversion postings, Prev: Reporting at cost, Up: Cost reporting + +21.3 Equity conversion postings +=============================== + +There is a problem with the entries above - they are not conventional +Double Entry Bookkeeping (DEB) notation, and because of the "magical" +transformation of one commodity into another, they cause an imbalance in +the Accounting Equation. This shows up as a non-zero grand total in +balance reports like 'hledger bse'. + + For most hledger users, this doesn't matter in practice and can +safely be ignored ! But if you'd like to learn more, keep reading. + + Conventional DEB uses an extra pair of equity postings to balance the +transaction. Of course you can do this in hledger as well: + + *Variant 4* + +2022-01-01 + assets:dollars $-135 + assets:euros €100 + equity:conversion $135 + equity:conversion €-100 + + Now the transaction is perfectly balanced according to standard DEB, +and 'hledger bse''s total will not be disrupted. + + And, hledger can still infer the cost for cost reporting, but it's +not done by default - you must add the '--infer-costs' flag like so: + +$ hledger print --infer-costs +2022-01-01 one hundred euros purchased at $1.35 each + assets:dollars $-135 @@ €100 + assets:euros €100 + equity:conversion $135 + equity:conversion €-100 + +$ hledger bal --infer-costs -B + €-100 assets:dollars + €100 assets:euros +-------------------- + 0 + + Here are some downsides of this kind of entry: + + * The per-unit cost basis is not easy to read. + + * Instead of '-B' you must remember to type '-B --infer-costs'. + + * '--infer-costs' works only where hledger can identify the two + equity:conversion postings and match them up with the two + non-equity postings. So writing the journal entry in a particular + format becomes more important. More on this below. + + +File: hledger.info, Node: Inferring equity conversion postings, Next: Combining costs and equity conversion postings, Prev: Equity conversion postings, Up: Cost reporting + +21.4 Inferring equity conversion postings +========================================= + +Can we go in the other direction ? Yes, if you have transactions +written with the @/@@ cost notation, hledger can infer the missing +equity postings, if you add the '--infer-equity' flag. Eg: + +2022-01-01 + assets:dollars -$135 + assets:euros €100 @ $1.35 + +$ hledger print --infer-equity +2022-01-01 + assets:dollars $-135 + assets:euros €100 @ $1.35 + equity:conversion:$-€:€ €-100 + equity:conversion:$-€:$ $135.00 + + The equity account names will be "equity:conversion:A-B:A" and +"equity:conversion:A-B:B" where A is the alphabetically first commodity +symbol. You can customise the "equity:conversion" part by declaring an +account with the 'V'/'Conversion' account type. + + Note you will need to add account declarations for these to your +journal, if you use 'check accounts' or 'check --strict'. + + +File: hledger.info, Node: Combining costs and equity conversion postings, Next: Requirements for detecting equity conversion postings, Prev: Inferring equity conversion postings, Up: Cost reporting + +21.5 Combining costs and equity conversion postings +=================================================== + +Finally, you can use both the @/@@ cost notation and equity postings at +the same time. This in theory gives the best of all worlds - preserving +the accounting equation, revealing the per-unit cost basis, and +providing more flexibility in how you write the entry: + + *Variant 5* + +2022-01-01 one hundred euros purchased at $1.35 each + assets:dollars $-135 + equity:conversion $135 + equity:conversion €-100 + assets:euros €100 @ $1.35 + + All the other variants above can (usually) be rewritten to this final +form with: + +$ hledger print -x --infer-costs --infer-equity + + Downsides: + + * The precise format of the journal entry becomes more important. If + hledger can't detect and match up the cost and equity postings, it + will give a transaction balancing error. + + * The add command does not yet accept this kind of entry (#2056). + + * This is the most verbose form. + + +File: hledger.info, Node: Requirements for detecting equity conversion postings, Next: Infer cost and equity by default ?, Prev: Combining costs and equity conversion postings, Up: Cost reporting + +21.6 Requirements for detecting equity conversion postings +========================================================== + +'--infer-costs' has certain requirements (unlike '--infer-equity', which +always works). It will infer costs only in transactions with: + + * Two non-equity postings, in different commodities. Their order is + significant: the cost will be added to the first of them. + + * Two postings to equity conversion accounts, next to one another, + which balance the two non-equity postings. This balancing is + checked to the same precision (number of decimal places) used in + the conversion posting's amount. Equity conversion accounts are: + + * any accounts declared with account type 'V'/'Conversion', or + their subaccounts + * otherwise, accounts named 'equity:conversion', 'equity:trade', + or 'equity:trading', or their subaccounts. + + And multiple such four-posting groups can coexist within a single +transaction. When '--infer-costs' fails, it does not infer a cost in +that transaction, and does not raise an error (ie, it infers costs where +it can). + + Reading variant 5 journal entries, combining cost notation and equity +postings, has all the same requirements. When reading such an entry +fails, hledger raises an "unbalanced transaction" error. + + +File: hledger.info, Node: Infer cost and equity by default ?, Prev: Requirements for detecting equity conversion postings, Up: Cost reporting + +21.7 Infer cost and equity by default ? +======================================= + +Should '--infer-costs' and '--infer-equity' be enabled by default ? Try +using them always, eg with a shell alias: + +alias h="hledger --infer-equity --infer-costs" + + and let us know what problems you find. + + +File: hledger.info, Node: Value reporting, Next: PART 4 COMMANDS, Prev: Cost reporting, Up: Top + +22 Value reporting +****************** + +hledger can also show amounts "at market value", converted to some other +commodity using the market price or conversion rate on a certain date. + + This is controlled by the '--value=TYPE[,COMMODITY]' option. We also +provide simpler '-V' and '-X COMMODITY' aliases for this, which are +often sufficient. The market prices are declared with a special 'P' +directive, and/or they can be inferred from the costs recorded in +transactions, by using the '--infer-market-prices' flag. + +* Menu: + +* -X Value in specified commodity:: +* -V Value in default commoditys:: +* Valuation date:: +* Finding market price:: +* --infer-market-prices market prices from transactions:: +* Valuation commodity:: +* --value Flexible valuation:: +* Valuation examples:: +* Interaction of valuation and queries:: +* Effect of valuation on reports:: + + +File: hledger.info, Node: -X Value in specified commodity, Next: -V Value in default commoditys, Up: Value reporting + +22.1 -X: Value in specified commodity +===================================== + +The '-X COMM' (or '--exchange=COMM') option converts amounts to their +market value in the specified commodity, using the market prices in +effect on the _valuation date(s)_, if any. (More on these in a minute.) + + Use this when you want to (eg) show everything in your base currency +as far as possible. (Commodities for which no conversion rate can be +found, will not be converted.) + + COMM should be the full commodity symbol or name. Remember to quote +special shell characters, if needed. Some examples: + + * '-X€' + * '-X$' (nothing after $, no quoting needed) + * '-X CNY' (the space after -X is optional) + * '-X 'red apples'' + * '-X 'r&r'' + + +File: hledger.info, Node: -V Value in default commoditys, Next: Valuation date, Prev: -X Value in specified commodity, Up: Value reporting + +22.2 -V: Value in default commodity(s) +====================================== + +The '-V/--market' flag is a variant of '-X' where you don't have to +specify COMM. Instead it tries to guess a _default valuation commodity_ +for each original commodity, based on the market prices in effect on the +valuation date(s). + + '-V' can often be a convenient shortcut for '-X MYCURRENCY', but not +always; depending on your data it could guess multiple valuation +commodities. Usually you want to convert to a single commodity, so it's +better to use '-X', unless you're sure '-V' is doing what you want. + + +File: hledger.info, Node: Valuation date, Next: Finding market price, Prev: -V Value in default commoditys, Up: Value reporting + +22.3 Valuation date +=================== + +Market prices can change from day to day. hledger will use the prices +on a particular valuation date (or on more than one date). By default +hledger uses "end" dates for valuation. More specifically: + + * For single period reports (including normal print and register + reports): + * If an explicit report end date is specified, that is used. + * Otherwise the latest transaction date or non-future P + directive date is used. + + * 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. + + +File: hledger.info, Node: Finding market price, Next: --infer-market-prices market prices from transactions, Prev: Valuation date, Up: Value reporting + +22.4 Finding market price +========================= + +To convert a commodity A to its market value in another commodity B, +hledger looks for a suitable market price (exchange rate) as follows, in +this order of preference: + + 1. A _declared market price_ or _inferred market price_: A's latest + market price in B on or before the valuation date as declared by a + P directive, or (with the '--infer-market-prices' flag) inferred + from costs. + + 2. A _reverse market price_: the inverse of a declared or inferred + market price from B to A. + + 3. A _forward chain of market prices_: a synthetic price formed by + combining the shortest chain of "forward" (only 1 above) market + prices, leading from A to B. + + 4. _Any chain of market prices_: a chain of any market prices, + including both forward and reverse prices (1 and 2 above), leading + from A to B. + + There is a limit to the length of these price chains; if hledger +reaches that length without finding a complete chain or exhausting all +possibilities, it will give up (with a "gave up" message visible in +'--debug=2' output). That limit is currently 1000. + + Amounts for which no suitable market price can be found, are not +converted. + + +File: hledger.info, Node: --infer-market-prices market prices from transactions, Next: Valuation commodity, Prev: Finding market price, Up: Value reporting + +22.5 -infer-market-prices: market prices from transactions +========================================================== + +Normally, market value in hledger is fully controlled by, and requires, +P directives in your journal. Since adding and updating those can be a +chore, and since transactions usually take place at close to market +value, why not use the recorded costs as additional market prices (as +Ledger does) ? Adding the '--infer-market-prices' flag to '-V', '-X' or +'--value' enables this. + + So for example, 'hledger bs -V --infer-market-prices' will get market +prices both from P directives and from transactions. If both occur on +the same day, the P directive takes precedence. + + There is a downside: value reports can sometimes be affected in +confusing/undesired ways by your journal entries. If this happens to +you, read all of this Value reporting section carefully, and try adding +'--debug' or '--debug=2' to troubleshoot. + + '--infer-market-prices' can infer market prices from: + + * multicommodity transactions with explicit prices ('@'/'@@') + + * multicommodity transactions with implicit prices (no '@', two + commodities, unbalanced). (With these, the order of postings + matters. 'hledger print -x' can be useful for troubleshooting.) + + * multicommodity transactions with equity postings, if cost is + inferred with '--infer-costs'. + + There is a limitation (bug) currently: when a valuation commodity is +not specified, prices inferred with '--infer-market-prices' do not help +select a default valuation commodity, as 'P' prices would. So +conversion might not happen because no valuation commodity was detected +('--debug=2' will show this). To be safe, specify the valuation +commmodity, eg: + + * '-X EUR --infer-market-prices', not '-V --infer-market-prices' + * '--value=then,EUR --infer-market-prices', not '--value=then + --infer-market-prices' + + Signed costs and market prices can be confusing. For reference, here +is the current behaviour, since hledger 1.25. (If you think it should +work differently, see #1870.) + +2022-01-01 Positive Unit prices + a A 1 + b B -1 @ A 1 + +2022-01-01 Positive Total prices + a A 1 + b B -1 @@ A 1 + + +2022-01-02 Negative unit prices + a A 1 + b B 1 @ A -1 + +2022-01-02 Negative total prices + a A 1 + b B 1 @@ A -1 + + +2022-01-03 Double Negative unit prices + a A -1 + b B -1 @ A -1 + +2022-01-03 Double Negative total prices + a A -1 + b B -1 @@ A -1 + + All of the transactions above are considered balanced (and on each +day, the two transactions are considered equivalent). Here are the +market prices inferred for B: + +$ hledger -f- --infer-market-prices prices +P 2022-01-01 B A 1 +P 2022-01-01 B A 1.0 +P 2022-01-02 B A -1 +P 2022-01-02 B A -1.0 +P 2022-01-03 B A -1 +P 2022-01-03 B A -1.0 + + +File: hledger.info, Node: Valuation commodity, Next: --value Flexible valuation, Prev: --infer-market-prices market prices from transactions, Up: Value reporting + +22.6 Valuation commodity +======================== + +*When you specify a valuation commodity ('-X COMM' or '--value +TYPE,COMM'):* +hledger will convert all amounts to COMM, wherever it can find a +suitable market price (including by reversing or chaining prices). + + *When you leave the valuation commodity unspecified ('-V' or '--value +TYPE'):* +For each commodity A, hledger picks a default valuation commodity as +follows, in this order of preference: + + 1. The price commodity from the latest P-declared market price for A + on or before valuation date. + + 2. The price commodity from the latest P-declared market price for A + on any date. (Allows conversion to proceed when there are inferred + prices before the valuation date.) + + 3. If there are no P directives at all (any commodity or date) and the + '--infer-market-prices' flag is used: the price commodity from the + latest transaction-inferred price for A on or before valuation + date. + + This means: + + * If you have P directives, they determine which commodities '-V' + will convert, and to what. + + * If you have no P directives, and use the '--infer-market-prices' + flag, costs determine it. + + Amounts for which no valuation commodity can be found are not +converted. + + +File: hledger.info, Node: --value Flexible valuation, Next: Valuation examples, Prev: Valuation commodity, Up: Value reporting + +22.7 -value: Flexible valuation +=============================== + +'-V' and '-X' are special cases of the more general '--value' option: + + --value=TYPE[,COMM] TYPE is then, end, now or YYYY-MM-DD. + COMM is an optional commodity symbol. + Shows amounts converted to: + - default valuation commodity (or COMM) using market prices at posting dates + - default valuation commodity (or COMM) using market prices at period end(s) + - default valuation commodity (or COMM) using current market prices + - default valuation commodity (or COMM) using market prices at some date + + The TYPE part selects cost or value and valuation date: + +'--value=then' + + Convert amounts to their value in the default valuation commodity, + using market prices on each posting's date. +'--value=end' + + Convert amounts to their value in the default valuation commodity, + using market prices on the last day of the report period (or if + unspecified, the journal's end date); or in multiperiod reports, + market prices on the last day of each subperiod. +'--value=now' + + Convert amounts to their value in the default valuation commodity + using current market prices (as of when report is generated). +'--value=YYYY-MM-DD' + + Convert amounts to their value in the default valuation commodity + using market prices on this date. + + To select a different valuation commodity, add the optional ',COMM' +part: a comma, then the target commodity's symbol. Eg: +*'--value=now,EUR'*. hledger will do its best to convert amounts to +this commodity, deducing market prices as described above. + + +File: hledger.info, Node: Valuation examples, Next: Interaction of valuation and queries, Prev: --value Flexible valuation, Up: Value reporting + +22.8 Valuation examples +======================= + +Here are some quick examples of '-V': + +; one euro is worth this many dollars from nov 1 +P 2016/11/01 € $1.10 + +; purchase some euros on nov 3 +2016/11/3 + assets:euros €100 + assets:checking + +; the euro is worth fewer dollars by dec 21 +P 2016/12/21 € $1.03 + + How many euros do I have ? + +$ hledger -f t.j bal -N euros + €100 assets:euros + + What are they worth at end of nov 3 ? + +$ hledger -f t.j bal -N euros -V -e 2016/11/4 + $110.00 assets:euros + + What are they worth after 2016/12/21 ? (no report end date +specified, defaults to today) + +$ hledger -f t.j bal -N euros -V + $103.00 assets:euros + + Here are some examples showing the effect of '--value', as seen with +'print': + +P 2000-01-01 A 1 B +P 2000-02-01 A 2 B +P 2000-03-01 A 3 B +P 2000-04-01 A 4 B + +2000-01-01 + (a) 1 A @ 5 B + +2000-02-01 + (a) 1 A @ 6 B + +2000-03-01 + (a) 1 A @ 7 B + + Show the cost of each posting: + +$ hledger -f- print --cost +2000-01-01 + (a) 5 B + +2000-02-01 + (a) 6 B + +2000-03-01 + (a) 7 B + + Show the value as of the last day of the report period (2000-02-29): + +$ hledger -f- print --value=end date:2000/01-2000/03 +2000-01-01 + (a) 2 B + +2000-02-01 + (a) 2 B + + With no report period specified, the latest transaction date or price +date is used as valuation date (2000-04-01): + +$ hledger -f- print --value=end +2000-01-01 + (a) 3 B + +2000-02-01 + (a) 3 B + +2000-03-01 + (a) 3 B + + The value today is the same (the 2000-04-01 price is still in +effect): + +$ hledger -f- print --value=now +2000-01-01 + (a) 4 B + +2000-02-01 + (a) 4 B + +2000-03-01 + (a) 4 B + + Show the value on 2000/01/15: + +$ hledger -f- print --value=2000-01-15 +2000-01-01 + (a) 1 B + +2000-02-01 + (a) 1 B + +2000-03-01 + (a) 1 B + + +File: hledger.info, Node: Interaction of valuation and queries, Next: Effect of valuation on reports, Prev: Valuation examples, Up: Value reporting + +22.9 Interaction of valuation and queries +========================================= + +When matching postings based on queries in the presence of valuation, +the following happens: + + 1. The query is separated into two parts: + 1. the currency ('cur:') or amount ('amt:'). + 2. all other parts. + + 2. The postings are matched to the currency and amount queries based + on pre-valued amounts. + 3. Valuation is applied to the postings. + 4. The postings are matched to the other parts of the query based on + post-valued amounts. + + Related: #1625 + + +File: hledger.info, Node: Effect of valuation on reports, Prev: Interaction of valuation and queries, Up: Value reporting + +22.10 Effect of valuation on reports +==================================== + +Here is a reference for how valuation is supposed to affect each part of +hledger's reports. It may be useful when troubleshooting. If you find +problems, please report them, ideally with a reproducible example. +Related: #329, #1083. + + First, a quick glossary: + +_cost_ + + calculated using price(s) recorded in the transaction(s). +_value_ + + market value using available market price declarations, or the + unchanged amount if no conversion rate can be found. +_report start_ + + the first day of the report period specified with -b or -p or + date:, otherwise today. +_report or journal start_ + + the first day of the report period specified with -b or -p or + date:, otherwise the earliest transaction date in the journal, + otherwise today. +_report end_ + + the last day of the report period specified with -e or -p or date:, + otherwise today. +_report or journal end_ + + the last day of the report period specified with -e or -p or date:, + otherwise the latest transaction date in the journal, otherwise + today. +_report interval_ + + a flag (-D/-W/-M/-Q/-Y) or period expression that activates the + report's multi-period mode (whether showing one or many + subperiods). + +Report '-B', '-V', '-X' '--value=then' '--value=end''--value=DATE', +type '--cost' '--value=now' +------------------------------------------------------------------------------ +*print* +posting cost value at value at posting value at value +amounts report end date report or at + or today journal DATE/today + end +balance unchanged unchanged unchanged unchanged unchanged +assertions/assignments +*register* +starting cost value at valued at day value at value +balance report or each historical report or at +(-H) journal posting was made journal DATE/today + end end +starting cost value at valued at day value at value +balance day before each historical day before at +(-H) report or posting was made report or DATE/today +with journal journal +report start start +interval +posting cost value at value at posting value at value +amounts report or date report or at + journal journal DATE/today + end end +summary summarised value at sum of postings value at value +posting cost period in interval, period at +amounts ends valued at ends DATE/today +with interval start +report +interval +running sum/average sum/average sum/average of sum/average sum/average +total/averageof of displayed values of of + displayed displayed displayed displayed + values values values values +*balance +(bs, +bse, cf, +is)* +balance sums of value at value at posting value at value +changes costs report end date report or at + or today journal DATE/today + of sums of end of of + postings sums of sums + postings of + postings +budget like like like balance like like +amounts balance balance changes balances balance +(-budget) changes changes changes +grand sum of sum of sum of displayed sum of sum of +total displayed displayed valued displayed displayed + values values values values +*balance +(bs, +bse, cf, +is) with +report +interval* +starting sums of value at sums of values value at sums +balances costs of report of postings report of +(-H) postings start of before report start of postings + before sums of start at sums of before + report all respective all report + start postings posting dates postings start + before before + report report + start start +balance sums of same as sums of values balance value +changes costs of -value=end of postings in change in at +(bal, postings period at each DATE/today +is, bs in period respective period, of +-change, posting dates valued at sums +cf period of +-change) ends postings +end sums of same as sums of values period end value +balances costs of -value=end of postings from balances, at +(bal -H, postings before period valued at DATE/today +is -H, from start to period period of +bs, cf) before end at ends sums + report respective of + start to posting dates postings + period end +budget like like like balance like like +amounts balance balance changes/end balances balance +(-budget) changes/end changes/end balances changes/end + balances balances balances +row sums, sums, sums, averages sums, sums, +totals, averages averages of displayed averages averages +row of of values of of +averages displayed displayed displayed displayed +(-T, -A) values values values values +column sums of sums of sums of sums of sums +totals displayed displayed displayed values displayed of + values values values displayed + values +grand sum, sum, sum, average of sum, sum, +total, average of average of column totals average of average +grand column column column of +average totals totals totals column + totals + + '--cumulative' is omitted to save space, it works like '-H' but with +a zero starting balance. + + +File: hledger.info, Node: PART 4 COMMANDS, Next: Help commands, Prev: Value reporting, Up: Top + +23 PART 4: COMMANDS +******************* + +Here are hledger's standard subcommands. You can list these by running +'hledger'. If you have installed more add-on commands, they also will +be listed. + + In the following command docs, each command's specific options are +shown. Most commands also support the general options described above, +though some of them might have no effect. (Usually if there's a +sensible way for a general option to affect a command, it will.) You +can list all of a command's options by running 'hledger CMD -h'. + + *Help commands* + + * commands - show the hledger commands list (default) + * demo - show small hledger demos in the terminal + * help - show the hledger manual with info, man, or pager + + *User interface commands* + + * repl - run commands from an interactive prompt + * run - run commands from a script + * ui - (if installed) run hledger's terminal UI + * web - (if installed) run hledger's web UI + + *Data entry commands* + + * add - add transactions using terminal prompts + * import - add new transactions from other files, eg CSV files + + *Basic report commands* + + * accounts - show account names + * codes - show transaction codes + * commodities - show commodity/currency symbols + * descriptions - show transaction descriptions + * files - show input file paths + * notes - show note parts of transaction descriptions + * payees - show payee parts of transaction descriptions + * prices - show market prices + * stats - show journal statistics + * tags - show tag names + + *Standard report commands* + + * print - show transactions or export journal data + * aregister (areg) - show transactions in a particular account + * register (reg) - show postings in one or more accounts & running + total + * balancesheet (bs) - show assets, liabilities and net worth + * balancesheetequity (bse) - show assets, liabilities and equity + * cashflow (cf) - show changes in liquid assets + * incomestatement (is) - show revenues and expenses + + *Advanced report commands* + + * balance (bal) - show balance changes, end balances, budgets, + gains.. + * roi - show return on investments + + *Chart commands* + + * activity - show bar charts of posting counts per period + + *Data generation commands* + + * close - generate balance-zeroing/restoring transactions + * rewrite - generate auto postings, like print -auto + + *Maintenance commands* + + * check - check for various kinds of error in the data + * diff - compare account transactions in two journal files + * setup - check and show the status of the hledger installation + * test - run self tests + + Next, these commands are described in detail. + + +File: hledger.info, Node: Help commands, Next: User interface commands, Prev: PART 4 COMMANDS, Up: Top + +24 Help commands +**************** + +* Menu: + +* commands:: +* demo:: +* help:: + + +File: hledger.info, Node: commands, Next: demo, Up: Help commands + +24.1 commands +============= + +Show the hledger commands list. + +Flags: + --builtin show only builtin commands, not addons + + +File: hledger.info, Node: demo, Next: help, Prev: commands, Up: Help commands + +24.2 demo +========= + +Play demos of hledger usage in the terminal, if asciinema is installed. + +Flags: + -s --speed=SPEED playback speed (1 is original speed, .5 is half, 2 + is double, etc (default: 2)) + + Run this command with no argument to list the demos. To play a demo, +write its number or a prefix or substring of its title. Tips: + + Make your terminal window large enough to see the demo clearly. + + Use the -s/-speed SPEED option to set your preferred playback speed, +eg '-s4' to play at 4x original speed or '-s.5' to play at half speed. +The default speed is 2x. + + During playback, several keys are available: SPACE to pause/unpause, +. to step forward (while paused), CTRL-c quit. + + Examples: + +$ hledger demo # list available demos +$ hledger demo 1 # play the first demo at default speed (2x) +$ hledger demo install -s4 # play the "install" demo at 4x speed + + This command is experimental: there aren't many useful demos yet. + + +File: hledger.info, Node: help, Prev: demo, Up: Help commands + +24.3 help +========= + +Show the hledger user manual with 'info', 'man', or a pager. With a +(case insensitive) TOPIC argument, try to open it at that section +heading. + +Flags: + -i show the manual with info + -m show the manual with man + -p show the manual with $PAGER or less + (less is always used if TOPIC is specified) + + This command shows the hledger manual built in to your hledger +executable. It can be useful when offline, or when you prefer the +terminal to a web browser, or when the appropriate hledger manual or +viewers are not installed properly on your system. + + By default it chooses the best viewer found in $PATH, trying in this +order: 'info', 'man', '$PAGER', 'less', 'more', stdout. (If a TOPIC is +specified, '$PAGER' and 'more' are not tried.) You can force the use of +info, man, or a pager with the '-i', '-m', or '-p' flags. If no viewer +can be found, or if running non-interactively, it just prints the manual +to stdout. + + When using 'info', TOPIC can match either the full heading or a +prefix. If your 'info --version' is < 6, you'll need to upgrade it, eg +with ''brew install texinfo'' on mac. + + When using 'man' or 'less', TOPIC must match the full heading. For a +prefix match, you can write ''TOPIC.*''. + + Examples + +$ hledger help -h # show the help command's usage +$ hledger help # show the manual with info, man or $PAGER +$ hledger help 'time periods' # show the manual's "Time periods" topic +$ hledger help 'time periods' -m # use man, even if info is installed + + +File: hledger.info, Node: User interface commands, Next: Data entry commands, Prev: Help commands, Up: Top + +25 User interface commands +************************** + +* Menu: + +* repl:: +* run:: +* ui:: +* web:: + + +File: hledger.info, Node: repl, Next: run, Up: User interface commands + +25.1 repl +========= + +Start an interactive prompt, where you can run any of hledger's +commands. Data files are parsed just once, so the commands run faster. + +Flags: +no command-specific flags + + This command is experimental and could change in the future. + + 'hledger repl' starts a read-eval-print loop (REPL) where you can +enter commands interactively. As with the 'run' command, each input +file (or each input file/input options combination) is parsed just once, +so commands will run more quickly than if you ran them individually at +the command line. + + Also like 'run', the input file(s) specified for the 'repl' command +will be the default input for all interactive commands. You can +override this temporarily by specifying an '-f' option in particular +commands. But note that commands will not see any changes made to input +files (eg by 'add') until you exit and restart the REPL. + + The command syntax is the same as with 'run': + + * enter one hledger command at a time, without the usual 'hledger' + first word + * empty lines and comment text from '#' to end of line are ignored + * use single or double quotes to quote arguments when needed + * type 'exit' or 'quit' or control-D to exit the REPL. + + While it is running, the REPL remembers your command history, and you +can navigate in the usual ways: + + * Keypad or Emacs navigation keys to edit the current command line + * UP/DOWN or control-P/control-N to step back/forward through history + * control-R to search for a past command + * TAB to complete file paths. + + Generally 'repl' command lines should feel much like the normal +hledger CLI, but you may find differences. 'repl' is a little stricter; +eg it requires full command names or official abbreviations (as seen in +the commands list). + + The 'commands' and 'help' commands, and the command help flags ('CMD +--tldr', 'CMD -h/--help', 'CMD --info', 'CMD --man'), can be useful. + + You can type control-C to cancel a long-running command (but only +once; typing it a second time will exit the REPL). + + And in most shells you can type control-Z to temporarily exit to the +shell (and then 'fg' to return to the REPL). + +* Menu: + +* Examples:: + + +File: hledger.info, Node: Examples, Up: repl + +25.1.1 Examples +--------------- + +Start the REPL and enter some commands: + +$ hledger repl +Enter hledger commands. To exit, enter 'quit' or 'exit', or send EOF. +% stats +Main file : .../2025.journal +... +% stats -f 2024/2024.journal +Main file : .../2024.journal +... +% stats +Main file : .../2025.journal +... + + or: + +$ hledger repl -f some.journal +Enter hledger commands. To exit, enter 'quit' or 'exit', or send EOF. +% bs +... +% print -b 'last week' +... +% bs -f other.journal +... + + +File: hledger.info, Node: run, Next: ui, Prev: repl, Up: User interface commands + +25.2 run +======== + +Run a sequence of hledger commands, provided as files or command line +arguments. Data files are parsed just once, so the commands run faster. + +Flags: +no command-specific flags + + This command is experimental and could change in the future. + + You can use 'run' in three ways: + + * 'hledger run -- CMD1 -- CMD2 -- CMD3' - read commands from the + command line, separated by '--' + * 'hledger run SCRIPTFILE1 SCRIPTFILE2' - read commands from one or + more files + * 'cat SCRIPTFILE1 | hledger run' - read commands from standard + input. + + 'run' first loads the input file(s) specified by 'LEDGER_FILE' or by +'-f' options, in the usual way. Then it runs each command in turn, each +using the same input data. But if you want a particular command to use +different input, you can specify an '-f' option within that command. +This will override (not add to) the default input, just for that +command. + + Each input file (more precisely, each combination of input file and +input options) is parsed only once. This means that commands will not +see any changes made to these files, until the next run. But the +commands will run more quickly than if run individually (typically about +twice as fast). + + Command scripts, whether in a file or written on the command line, +have a simple syntax: + + * each line may contain a single hledger command and its arguments, + without the usual 'hledger' first word + * empty lines are ignored + * text from '#' to end of line is a comment, and ignored + * you can use single or double quotes to quote arguments when needed, + as on the command line + * these extra commands are available: 'echo TEXT' prints some text, + and 'exit' or 'quit' ends the run. + + On unix systems you can use '#!/usr/bin/env hledger run' in the first +line of a command file to make it a runnable script. If that gives an +error, use '#!/usr/bin/env -S hledger run'. + + It's ok to use the 'run' command recursively within a command script. + + You may find some differences in behaviour between 'run' command +lines and normal hledger command lines. 'run' is a little stricter; eg +it requires full command names or official abbreviations (as seen in the +commands list), and command options must be written after the command +name. + +* Menu: + +* Examples: Examples 2. + + +File: hledger.info, Node: Examples 2, Up: run + +25.2.1 Examples +--------------- + +Run commands from the command line: + +hledger -f some.journal run -- balance assets --depth 2 -- balance liabilities -f /some/other.journal --depth 3 --transpose -- stats + + This would load 'some.journal', run 'balance assets --depth 2' on it, +then run 'balance liabilities --depth 3 --transpose' on +'/some/other.journal', and finally run 'stats' on 'some.journal' + + Run commands from standard input: + +(echo "files"; echo "stats") | hledger -f some.journal run + + Run commands as a script: + +$ cat report +#!/usr/bin/env -S hledger run -f some.journal + +echo "List of accounts in some.journal" +accounts + +echo "Assets of some.journal" +balance assets --depth 2 + +echo "Liabilities from /some/other.journal" +balance liabilities -f /some/other.journal --depth 3 --transpose + +echo "Commands from another.script, applied to another.journal" +run -f another.journal another.script + +$ chmod +x report +$ ./report +List of accounts in some.journal +... + + +File: hledger.info, Node: ui, Next: web, Prev: run, Up: User interface commands + +25.3 ui +======= + +Runs hledger-ui (if installed). + + +File: hledger.info, Node: web, Prev: ui, Up: User interface commands + +25.4 web +======== + +Runs hledger-web (if installed). + + +File: hledger.info, Node: Data entry commands, Next: Basic report commands, Prev: User interface commands, Up: Top + +26 Data entry commands +********************** + +* Menu: + +* add:: +* add and balance assertions:: +* add and balance assignments:: +* import:: + + +File: hledger.info, Node: add, Next: add and balance assertions, Up: Data entry commands + +26.1 add +======== + +Add new transactions to a journal file, with interactive prompting. + +Flags: + --no-new-accounts don't allow creating new accounts + + Many hledger users edit their journals directly with a text editor, +or generate them from CSV. For more interactive data entry, there is the +'add' command, which prompts interactively on the console for new +transactions, and appends them to the main journal file (which should be +in journal format). Existing transactions are not changed. This is one +of the few hledger commands that writes to the journal file (see also +'import'). + + To use it, just run 'hledger add' and follow the prompts. You can +add as many transactions as you like; when you are finished, enter '.' +or press control-d or control-c to exit. + + Features: + + * add tries to provide useful defaults, using the most similar (by + description) recent transaction (filtered by the query, if any) as + a template. + * You can also set the initial defaults with command line arguments. + * Readline-style edit keys can be used during data entry. + * The tab key will auto-complete whenever possible - accounts, + payees/descriptions, dates ('yesterday', 'today', 'tomorrow'). If + the input area is empty, it will insert the default value. + * A parenthesised transaction code may be entered following a date. + * Comments and tags may be entered following a description or amount. + * If you make a mistake, enter '<' at any prompt to go one step + backward. + * Input prompts are displayed in a different colour when the terminal + supports it. + + Notes: + + * If you enter a number with no commodity symbol, and you have + declared a default commodity with a 'D' directive, you might expect + 'add' to add this symbol for you. It does not do this; we assume + that if you are using a 'D' directive you prefer not to see the + commodity symbol repeated on amounts in the journal. + * 'add' creates entries in journal format; it won't work with + timeclock or timedot files. + + Examples: + + * Record new transactions, saving to the default journal file: + + 'hledger add' + + * Add transactions to 2024.journal, but also load 2023.journal for + completions: + + 'hledger add --file 2024.journal --file 2023.journal' + + * Provide answers for the first four prompts: + + 'hledger add today 'best buy' expenses:supplies '$20'' + + There is a detailed tutorial at https://hledger.org/add.html. + + +File: hledger.info, Node: add and balance assertions, Next: add and balance assignments, Prev: add, Up: Data entry commands + +26.2 add and balance assertions +=============================== + +Since hledger 1.43, you can add a balance assertion by writing 'AMOUNT = +BALANCE' when asked for an amount. Eg '100 = 500'. + + Also, each time you enter a new amount, hledger re-checks all balance +assertions in the journal and rejects the new amount if it would make +any of them fail. You can run 'add' with '-I'/'--ignore-assertions' to +disable balance assertion checking. + + +File: hledger.info, Node: add and balance assignments, Next: import, Prev: add and balance assertions, Up: Data entry commands + +26.3 add and balance assignments +================================ + +Since hledger 1.50.3, you can add a balance assignment by writing '= +BALANCE' (or '==', '=*' etc) when asked for an amount. The missing +amount will be calculated automatically. + + 'add' normally won't let you add a new posting which is dated earlier +than an existing balance assignment. (Because when 'add' runs, existing +balance assignments have already been calculated and converted to +amounts and balance assertions.) You can allow it by disabling balance +assertion checking with '-I'. + + +File: hledger.info, Node: import, Prev: add and balance assignments, Up: Data entry commands + +26.4 import +=========== + +Import new transactions from one or more data files to the main journal. + +Flags: + --catchup just mark all transactions as already imported + --dry-run just show the transactions to be imported + + This command detects new transactions in one or more data files +specified as arguments, and appends them to the main journal. + + You can import from any input file format hledger supports, but +CSV/SSV/TSV files, downloaded from financial institutions, are the most +common import source. + + The import destination is the default journal file, or another +specified in the usual way with '$LEDGER_FILE' or '-f/--file'. It +should be in journal format. + + Examples: + +$ hledger import bank1-checking.csv bank1-savings.csv + +$ hledger import *.csv + +* Menu: + +* Import dry run:: +* Overlap detection:: +* First import:: +* Importing balance assignments:: +* Import and commodity styles:: +* Import archiving:: +* Import special cases:: + + +File: hledger.info, Node: Import dry run, Next: Overlap detection, Up: import + +26.4.1 Import dry run +--------------------- + +It's useful to preview the import by running first with '--dry-run', to +sanity check the range of dates being imported, and to check the effect +of your conversion rules if converting from CSV. Eg: + +$ hledger import bank.csv --dry-run + + The dry run output is valid journal format, so hledger can re-parse +it. If the output is large, you could show just the uncategorised +transactions like so: + +$ hledger import --dry-run bank.csv | hledger -f- -I print unknown + + You could also run this repeatedly to see the effect of edits to your +conversion rules: + +$ watchexec -- "hledger import --dry-run bank.csv | hledger -f- -I print unknown" + + Once the conversion and dates look good enough to import to your +journal, perhaps with some manual fixups to follow, you would do the +actual import: + +$ hledger import bank.csv + + +File: hledger.info, Node: Overlap detection, Next: First import, Prev: Import dry run, Up: import + +26.4.2 Overlap detection +------------------------ + +Reading CSV files is built in to hledger, and not specific to 'import'; +so you could also import by doing 'hledger -f bank.csv print +>>$LEDGER_FILE'. + + But 'import' is easier and provides some advantages. The main one is +that it avoids re-importing transactions it has seen on previous runs. +This means you don't have to worry about overlapping data in successive +downloads of your bank CSV; just download and 'import' as often as you +like, and only the new transactions will be imported each time. + + We don't call this "deduplication", as it's generally not possible to +reliably detect duplicates in bank CSV. Instead, 'import' remembers the +latest date processed previously in each CSV file (saving it in a hidden +file), and skips any records prior to that date. This works well for +most real-world CSV, where: + + 1. the data file name is stable (does not change) across imports + 2. the item dates are stable across imports + 3. the order of same-date items is stable across imports + 4. the newest items have the newest dates + + (Occasional violations of 2-4 are often harmless; you can reduce the +chance of disruption by downloading and importing more often.) + + Overlap detection is automatic, and shouldn't require much attention +from you, except perhaps at first import (see below). But here's how it +works: + + * For each 'FILE' being imported from: + + 1. hledger reads a file named '.latest.FILE' file in the same + directory, if any. This file contains the latest record date + previously imported from FILE, in YYYY-MM-DD format. If + multiple records with that date were imported, the date is + repeated on N lines. + + 2. hledger reads records from FILE. If a latest date was found in + step 1, any records before that date, and the first N records + on that date, are skipped. + + * After a successful import from all FILEs, without error and without + '--dry-run', hledger updates each FILE's '.latest.FILE' for next + time. + + If this goes wrong, it's relatively easy to repair: + + * You'll notice it before import when you preview with 'import + --dry-run'. + * Or after import when you try to reconcile your hledger account + balances with your bank. + * 'hledger print -f FILE.csv' will show all recently downloaded + transactions. Compare these with your journal. Copy/paste if + needed. + * Update your conversion rules and print again, if needed. + * You can manually update or remove the .latest file, or use 'import + --catchup FILE'. + * Download and import more often, eg twice a week, at least while you + are learning. It's easier to review and troubleshoot when there + are fewer transactions. + + +File: hledger.info, Node: First import, Next: Importing balance assignments, Prev: Overlap detection, Up: import + +26.4.3 First import +------------------- + +The first time you import from a file, when no corresponding .latest +file has been created yet, all of the records will be imported. + + But perhaps you have been entering the data manually, so you know +that all of these transactions are already recorded in the journal. In +this case you can run 'hledger import --catchup' once. This will create +a .latest file containing the latest CSV record date, so that none of +those records will be re-imported. + + Or, if you know that some but not all of the transactions are in the +journal, you can create the .latest file yourself. Eg, let's say you +previously recorded foobank transactions up to 2024-10-31 in the +journal. Then in the directory where you'll be saving 'foobank.csv', +you would create a '.latest.foobank.csv' file containing + +2024-10-31 + + Or if you had three foobank transactions recorded with that date, you +would repeat the date that many times: + +2024-10-31 +2024-10-31 +2024-10-31 + + Then 'hledger import foobank.csv [--dry-run]' will import only the +newer records. + + +File: hledger.info, Node: Importing balance assignments, Next: Import and commodity styles, Prev: First import, Up: import + +26.4.4 Importing balance assignments +------------------------------------ + +Journal entries added by import will have all posting amounts made +explicit (like 'print -x'). + + This means that any balance assignments in the imported entries would +need to be evaluated. But this generally isn't possible, as the main +file's account balances are not visible during import. So try to avoid +generating balance assignments with your CSV rules, or importing from a +journal that contains balance assignments. (Balance assignments are +best avoided anyway.) + + But if you must use them, eg because your CSV includes only balances: +you can import with 'print', which leaves implicit amounts implicit. +('print' can also do overlap detection like import, with the '--new' +flag): + +$ hledger print --new -f bank.csv >> $LEDGER_FILE + + (If you think 'import' should preserve implicit balances, please test +that and send a pull request.) + + +File: hledger.info, Node: Import and commodity styles, Next: Import archiving, Prev: Importing balance assignments, Up: import + +26.4.5 Import and commodity styles +---------------------------------- + +Amounts in entries added by import will be formatted according to the +journal's canonical commodity styles, as declared by 'commodity' +directives or inferred from the journal's amounts. + + Related: CSV > Amount decimal places. + + +File: hledger.info, Node: Import archiving, Next: Import special cases, Prev: Import and commodity styles, Up: import + +26.4.6 Import archiving +----------------------- + +When importing from a CSV rules file ('hledger import bank.rules'), you +can use the archive rule to enable automatic archiving of the data file. +After a successful import, the data file (specified by 'source') will be +moved to an archive folder ('data/', next to the rules file, +auto-created), and renamed similar to the rules file, with a date. This +can be useful for troubleshooting, detecting variations in your banks' +CSV data, regenerating entries with improved rules, etc. + + The 'archive' rule also causes 'import' to handle 'source' glob +patterns differently: when there are multiple matched files, it will +pick the oldest, not the newest. + + +File: hledger.info, Node: Import special cases, Prev: Import archiving, Up: import + +26.4.7 Import special cases +--------------------------- + +* Menu: + +* Deduplication:: +* Varying file name:: +* Multiple versions:: + + +File: hledger.info, Node: Deduplication, Next: Varying file name, Up: Import special cases + +26.4.7.1 Deduplication +...................... + +Here are two kinds of "deduplication" which 'import' does not handle +(and should not, because these can happen legitimately in financial +data): + + * Two or more of the new CSV records are identical, and generate + identical new journal entries. + * A new CSV record generates a journal entry identical to one(s) + already in the journal. + + +File: hledger.info, Node: Varying file name, Next: Multiple versions, Prev: Deduplication, Up: Import special cases + +26.4.7.2 Varying file name +.......................... + +If you have a download whose file name varies, you could rename it to a +fixed name after each download. Or you could use a CSV 'source' rule +with a suitable glob pattern, and import from the .rules file. + + +File: hledger.info, Node: Multiple versions, Prev: Varying file name, Up: Import special cases + +26.4.7.3 Multiple versions +.......................... + +Say you download 'bank.csv', import it, but forget to delete it from +your downloads folder. The next time you download it, your web browser +will save it as (eg) 'bank (2).csv'. The source rule's glob patterns +are for just this situation: instead of specifying 'source bank.csv', +specify 'source bank*.csv'. Then 'hledger -f bank.rules CMD' or +'hledger import bank.rules' will automatically pick the newest matched +file ('bank (2).csv'). + + Alternately, what if you download, but forget to import or delete, +then download again ? Now each of 'bank.csv' and 'bank (2).csv' might +contain data that's not in the other, and not in your journal. In this +case, it's best to import each of them in turn, oldest first (otherwise, +overlap detection could cause new records to be skipped). Enabling +import archiving ensures this. Then 'hledger import bank.rules; hledger +import bank.rules' will import and archive first 'bank.csv', then 'bank +(2).csv'. + + +File: hledger.info, Node: Basic report commands, Next: Standard report commands, Prev: Data entry commands, Up: Top + +27 Basic report commands +************************ + +* Menu: + +* accounts:: +* codes:: +* commodities:: +* descriptions:: +* files:: +* notes:: +* payees:: +* prices:: +* stats:: +* tags:: + + +File: hledger.info, Node: accounts, Next: codes, Up: Basic report commands + +27.1 accounts +============= + +List the account names used or declared in the journal. + +Flags: + -u --used list accounts used + -d --declared list accounts declared + --undeclared list accounts used but not declared + --unused list accounts declared but not used + --find list the first account matched by the first + argument (a case-insensitive infix regexp) + --types also show account types when known + --positions also show where accounts were declared + --directives show as account directives, for use in journals + -l --flat list/tree mode: show accounts as a flat list + (default) + -t --tree list/tree mode: show accounts as a tree + --drop=N flat mode: omit N leading account name parts + + This command lists account names - all of them by default. or just +the ones which have been used in transactions, or declared with +'account' directives, or used but not declared, or declared but not +used, or just the first account name matched by a pattern. + + You can add query arguments to select a subset of transactions or +accounts. + + 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 shows valid account directives which could be +pasted into a journal file. This is useful together with '--undeclared' +when updating your account declarations to satisfy 'hledger check +accounts'. + + The '--find' flag can be used to look up a single account name, in +the same way that the 'aregister' command does. It returns the +alphanumerically-first matched account name, or if none can be found, it +fails with a non-zero exit code. + + Examples: + +$ hledger accounts +assets:bank:checking +assets:bank:saving +assets:cash +expenses:food +expenses:supplies +income:gifts +income:salary +liabilities:debts + +$ hledger accounts --undeclared --directives >> $LEDGER_FILE +$ hledger check accounts + + +File: hledger.info, Node: codes, Next: commodities, Prev: accounts, Up: Basic report commands + +27.2 codes +========== + +List the codes seen in transactions, in the order parsed. + +Flags: +no command-specific flags + + This command prints the value of each transaction's code field, in +the order transactions were parsed. The transaction code is an optional +value written in parentheses between the date and description, often +used to store a cheque number, order number or similar. + + Transactions aren't required to have a code, and missing or empty +codes will not be shown by default. With the '-E'/'--empty' flag, they +will be printed as blank lines. + + You can add a query to select a subset of transactions. + + Examples: + +2022/1/1 (123) Supermarket + Food $5.00 + Checking + +2022/1/2 (124) Post Office + Postage $8.32 + Checking + +2022/1/3 Supermarket + Food $11.23 + Checking + +2022/1/4 (126) Post Office + Postage $3.21 + Checking + +$ hledger codes +123 +124 +126 + +$ hledger codes -E +123 +124 + +126 + + +File: hledger.info, Node: commodities, Next: descriptions, Prev: codes, Up: Basic report commands + +27.3 commodities +================ + +List the commodity symbols used or declared in the journal. + +Flags: + --used list commodities used + --declared list commodities declared + --undeclared list commodities used but not declared + --unused list commodities declared but not used + + This command lists commodity symbols/names - all of them by default, +or just the ones which have been used in transactions or 'P' directives, +or declared with 'commodity' directives, or used but not declared, or +declared but not used. + + You can add cur: query arguments to further limit the commodities. + + +File: hledger.info, Node: descriptions, Next: files, Prev: commodities, Up: Basic report commands + +27.4 descriptions +================= + +List the unique descriptions used in transactions. + +Flags: +no command-specific flags + + This command lists the unique descriptions that appear in +transactions, in alphabetic order. You can add a query to select a +subset of transactions. + + Example: + +$ hledger descriptions +Store Name +Gas Station | Petrol +Person A + + +File: hledger.info, Node: files, Next: notes, Prev: descriptions, Up: Basic report commands + +27.5 files +========== + +List all files included in the journal. With a REGEX argument, only +file names matching the regular expression (case sensitive) are shown. + +Flags: +no command-specific flags + + +File: hledger.info, Node: notes, Next: payees, Prev: files, Up: Basic report commands + +27.6 notes +========== + +List the unique notes that appear in transactions. + +Flags: +no command-specific flags + + This command lists the unique notes that appear in transactions, in +alphabetic order. You can add a query to select a subset of +transactions. The note is the part of the transaction description after +a | character (or if there is no |, the whole description). + + Example: + +$ hledger notes +Petrol +Snacks + + +File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: Basic report commands + +27.7 payees +=========== + +List the payee/payer names used or declared in the journal. + +Flags: + --used list payees used + --declared list payees declared + --undeclared list payees used but not declared + --unused list payees declared but not used + + This command lists unique payee/payer names - all of them by default, +or just the ones which have been used in transaction descriptions, or +declared with 'payee' directives, or used but not declared, or declared +but not used. + + The payee/payer name 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 or +payees. + + Example: + +$ hledger payees +Store Name +Gas Station +Person A + + +File: hledger.info, Node: prices, Next: stats, Prev: payees, Up: Basic report commands + +27.8 prices +=========== + +Print the market prices declared with P directives. With +-infer-market-prices, also show any additional prices inferred from +costs. With -show-reverse, also show additional prices inferred by +reversing known prices. + +Flags: + --show-reverse also show the prices inferred by reversing known + prices + + Price amounts are always displayed with their full precision, except +for reverse prices which are limited to 8 decimal digits. + + Prices can be filtered by a date:, cur: or amt: query. + + Generally if you run this command with -infer-market-prices +-show-reverse, it will show the same prices used internally to calculate +value reports. But if in doubt, you can inspect those directly by +running the value report with -debug=2. + + +File: hledger.info, Node: stats, Next: tags, Prev: prices, Up: Basic report commands + +27.9 stats +========== + +Show journal and performance statistics. + +Flags: + -v --verbose show more detailed output + -o --output-file=FILE write output to FILE. + + The stats command shows summary information for the whole journal, or +a matched part of it. With a reporting interval, it shows a report for +each report period. + + The default output is fairly impersonal, though it reveals the main +file name. With '-v/--verbose', more details are shown, like file +paths, included files, and commodity names. + + It also shows some run time statistics: + + * elapsed time + * throughput: the number of transactions processed per second + * live: the peak memory in use by the program to do its work + * alloc: the peak memory allocation from the OS as seen by GHC. + Measuring this externally, eg with GNU time, is more accurate; + usually that will be a larger number; sometimes (with swapping?) + smaller. + + The 'stats' command's run time is similar to that of a balance +report. + + Example: + +$ hledger stats -f examples/1ktxns-1kaccts.journal +Main file : .../1ktxns-1kaccts.journal +Included files : 0 +Txns span : 2000-01-01 to 2002-09-27 (1000 days) +Last txn : 2002-09-26 (7827 days ago) +Txns : 1000 (1.0 per day) +Txns last 30 days : 0 (0.0 per day) +Txns last 7 days : 0 (0.0 per day) +Payees/descriptions : 1000 +Accounts : 1000 (depth 10) +Commodities : 26 +Market prices : 1000 +Runtime stats : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc + + This command supports the -o/-output-file option (but not +-O/-output-format). + + +File: hledger.info, Node: tags, Prev: stats, Up: Basic report commands + +27.10 tags +========== + +List the tag names used or declared in the journal, or their values. + +Flags: + --used list tags used + --declared list tags declared + --undeclared list tags used but not declared + --unused list tags declared but not used + --values list tag values instead of tag names + --parsed show them in the order they were parsed (mostly), + including duplicates + + This command lists tag names - all of them by default, or just the +ones which have been used on transactions/postings/accounts, or declared +with 'tag' directives, or used but not declared, or declared but not +used. + + You can add one TAGREGEX argument, to show only tags whose name is +matched by this case-insensitive, infix-matching regular expression. + + After that, you can add query arguments to filter the transactions, +postings, or accounts providing tags. + + With '--values', 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.) + + Remember that accounts also acquire tags from their parents; postings +also acquire tags from their account and transaction; and transactions +also acquire tags from their postings. + + +File: hledger.info, Node: Standard report commands, Next: Advanced report commands, Prev: Basic report commands, Up: Top + +28 Standard report commands +*************************** + +* Menu: + +* print:: +* aregister:: +* register:: +* balancesheet:: +* balancesheetequity:: +* cashflow:: +* incomestatement:: + + +File: hledger.info, Node: print, Next: aregister, Up: Standard report commands + +28.1 print +========== + +Show full journal entries, representing transactions. + +Flags: + -x --explicit show all amounts explicitly + --invert display all amounts with reversed sign + --location add tags showing file paths and line numbers + -m --match=DESC fuzzy search for one recent transaction with + description closest to DESC + --new show only newer-dated transactions added in each + file since last run + --round=TYPE how much rounding or padding should be done when + displaying amounts ? + none - show original decimal digits, + as in journal (default) + soft - just add or remove decimal zeros + to match precision + hard - round posting amounts to precision + (can unbalance transactions) + all - also round cost amounts to precision + (can unbalance transactions) + --base-url=URLPREFIX in html output, generate links to hledger-web, + with this prefix. (Usually the base url shown by + hledger-web; can also be relative.) + -O --output-format=FMT select the output format. Supported formats: + txt, beancount, csv, tsv, html, fods, json, sql. + -o --output-file=FILE write output to FILE. A file extension matching + one of the above formats selects that format. + + The print command displays full journal entries (transactions) from +the journal file, sorted by date (or with '--date2', by secondary date). + + Directives and inter-transaction comments are not shown, currently. +This means the print command is somewhat lossy, and if you are using it +to reformat/regenerate your journal you should take care to also copy +over the directives and inter-transaction comments. + + Eg: + +$ hledger print -f examples/sample.journal date:200806 +2008/06/01 gift + assets:bank:checking $1 + income:gifts $-1 + +2008/06/02 save + assets:bank:saving $1 + assets:bank:checking $-1 + +2008/06/03 * eat & shop + expenses:food $1 + expenses:supplies $1 + assets:cash $-2 + +* Menu: + +* print amount explicitness:: +* print alignment:: +* print amount style:: +* print parseability:: +* print other features:: +* print output format:: + + +File: hledger.info, Node: print amount explicitness, Next: print alignment, Up: print + +28.1.1 print amount 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 alignment, Next: print amount style, Prev: print amount explicitness, Up: print + +28.1.2 print alignment +---------------------- + +Amounts are shown right-aligned within each transaction (but not aligned +across all transactions; you can achieve that with ledger-mode in +Emacs). + + +File: hledger.info, Node: print amount style, Next: print parseability, Prev: print alignment, Up: print + +28.1.3 print amount style +------------------------- + +Amounts will be displayed mostly in their commodity's display style, +with standardised symbol placement, decimal mark, and digit group marks. +This does not apply to their decimal digits; 'print' normally shows the +same decimal digits that are recorded in each journal entry. + + You can override the decimal precisions with 'print''s special +'--round' option (_since 1.32_). '--round' tries to show amounts with +their commodities' standard decimal precisions, increasingly strongly: + + * '--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, displaying more consistent +decimals where possible, without making entries unbalanced. + + 'hard' or 'all' can be good for stronger cleanup, when decimal +rounding is wanted. Note rounding can produce unbalanced journal +entries, perhaps requiring manual fixup. + + +File: hledger.info, Node: print parseability, Next: print other features, Prev: print amount style, Up: print + +28.1.4 print parseability +------------------------- + +Normally, print's output is a valid hledger journal, which you can +"pipe" to a second hledger command for further processing. This is +sometimes convenient for achieving certain kinds of query (though less +needed now that queries have become more powerful): + +# 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 + + But here are some things which can cause print's output to become +unparseable: + + * '--round' (see above) can disrupt transaction balancing. + * Account aliases or pivoting can disrupt account names, balance + assertions, or balance assignments. + * Value reporting also can disrupt balance assertions or balance + assignments. + * Auto postings can generate too many amountless postings. + * '--infer-costs or --infer-equity' can generate too-complex + redundant costs. + * Because print always shows transactions in date order, balance + assertions involving non-date-ordered transactions (and same-day + postings) could be disrupted. + + +File: hledger.info, Node: print other features, Next: print output format, Prev: print parseability, Up: print + +28.1.5 print, other features +---------------------------- + +With '-B'/'--cost', amounts with costs are shown converted to cost. + + With '--invert', posting amounts are shown with their sign flipped. +It could be useful if you have accidentally recorded some transactions +with the wrong signs. + + With '--new', print shows only transactions it has not seen on a +previous run. This uses the same deduplication system as the 'import' +command. (See import's docs for details.) + + With '-m DESC'/'--match=DESC', print shows one recent transaction +whose description is most similar to DESC. DESC should contain at least +two characters. If there is no similar-enough match, no transaction +will be shown and the program exit code will be non-zero. + + With '--location', print adds the source file and line number to +every transaction, as a tag. + + +File: hledger.info, Node: print output format, Prev: print other features, Up: print + +28.1.6 print output format +-------------------------- + +This command also supports the output destination and output format +options The output formats supported are 'txt', 'beancount' (_Added in +1.32_), 'csv', 'tsv' (_Added in 1.32_), 'json' and 'sql'. + + The 'beancount' format tries to produce Beancount-compatible output, +as follows: + + * Transaction and postings with unmarked status are converted to + cleared ('*') status. + * Transactions' payee and note are backslash-escaped and + double-quote-escaped and wrapped in double quotes. + * Transaction tags are copied to Beancount #tag format. + * Commodity symbols are converted to upper case, and a small number + of currency symbols like '$' are converted to the corresponding + currency names. + * Account name parts are capitalised and unsupported characters are + replaced with '-'. If an account name part does not begin with a + letter, or if the first part is not Assets, Liabilities, Equity, + Income, or Expenses, an error is raised. (Use '--alias' options to + bring your accounts into compliance.) + * An 'open' directive is generated for each account used, on the + earliest transaction date. + + Some limitations: + + * Balance assertions are removed. + * Balance assignments become missing amounts. + * Virtual and balanced virtual postings become regular postings. + * Directives are not converted. + + Here's an example of print's CSV output: + +$ hledger print -Ocsv +"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment" +"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","","" +"1","2008/01/01","","","","income","","income:salary","-1","$","1","","","" +"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","","" +"2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","","" +"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","","" +"3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","","" +"4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","","" +"4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","","" +"4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","","" +"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" +"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" + + * There is one CSV record per posting, with the parent transaction's + fields repeated. + * The "txnidx" (transaction index) field shows which postings belong + to the same transaction. (This number might change if transactions + are reordered within the file, files are parsed/included in a + different order, etc.) + * The amount is separated into "commodity" (the symbol) and "amount" + (numeric quantity) fields. + * The numeric amount is repeated in either the "credit" or "debit" + column, for convenience. (Those names are not accurate in the + accounting sense; it just puts negative amounts under credit and + zero or greater amounts under debit.) + + +File: hledger.info, Node: aregister, Next: register, Prev: print, Up: Standard report commands + +28.2 aregister +============== + +(areg) + + Show the transactions and running balances in one account, with each +transaction on one line. + +Flags: + --txn-dates filter strictly by transaction date, not posting + date. Warning: this can show a wrong running + balance. + --no-elide don't show only 2 commodities per amount + --cumulative accumulation mode: show running total from report + start date + -H --historical accumulation mode: show historical running + total/balance (includes postings before report + start date) (default) + --invert display all amounts with reversed sign + --heading=YN show heading row above table: yes (default) or no + -w --width=N set output width (default: terminal width). -wN,M + sets description width as well. + --align-all guarantee alignment across all lines (slower) + -O --output-format=FMT select the output format. Supported formats: + txt, html, csv, tsv, json. + -o --output-file=FILE write output to FILE. A file extension matching + one of the above formats selects that format. + + 'aregister' shows the overall transactions affecting a particular +account (and any subaccounts). Each report line represents one +transaction in this account. Transactions before the report start date +are included in the running balance ('--historical' mode is the +default). You can suppress this behaviour using the '--cumulative' +option. + + This is a more "real world", bank-like view than the 'register' +command (which shows individual postings, possibly from multiple +accounts, not necessarily in historical mode). As a quick rule of +thumb: + + * 'aregister' is best when reconciling real-world asset/liability + accounts + * 'register' is best when reviewing individual 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 historical balance report with similar arguments. + + Any additional arguments form a query which will filter the +transactions shown. Note some queries will disturb the running balance, +causing it to be different from the account's real-world running +balance. + + An example: this shows the transactions and historical running +balance during july, in the first account whose name contains +"checking": + +$ hledger areg checking date:jul + + Each 'aregister' line item shows: + + * the transaction's date (or the relevant posting's date if + different, see below) + * the names of all the other account(s) involved in this transaction + (probably abbreviated) + * the total change to this account's balance from this transaction + * the account's historical running balance after this transaction. + + Transactions making a net change of zero are not shown by default; +add the '-E/--empty' flag to show them. + + For performance reasons, column widths are chosen based on the first +1000 lines; this means unusually wide values in later lines can cause +visual discontinuities as column widths are adjusted. If you want to +ensure perfect alignment, at the cost of more time and memory, use the +'--align-all' flag. + + By default, 'aregister' shows a heading above the data. However, +when reporting in a language different from English, it is easier to +omit this heading and prepend your own one. For this purpose, use the +'--heading=no' option. + + This command also supports the output destination and output format +options. The output formats supported are 'txt', 'csv', 'tsv' (_Added +in 1.32_), 'html', 'fods' (_Added in 1.41_) and 'json'. + +* Menu: + +* aregister and posting dates:: + + +File: hledger.info, Node: aregister and posting dates, Up: aregister + +28.2.1 aregister and posting dates +---------------------------------- + +aregister always shows one line (and date and amount) per transaction. +But sometimes transactions have postings with different dates. Also, +not all of a transaction's postings may be within the report period. To +resolve this, aregister shows the earliest of the transaction's date and +posting dates that is in-period, and the sum of the in-period postings. +In other words it will show a combined line item with just the earliest +date, and the running balance will (temporarily, until the transaction's +last posting) be inaccurate. Use 'register -H' if you need to see the +individual postings. + + There is also a '--txn-dates' flag, which filters strictly by +transaction date, ignoring posting dates. This too can cause an +inaccurate running balance. + + +File: hledger.info, Node: register, Next: balancesheet, Prev: aregister, Up: Standard report commands + +28.3 register +============= + +(reg) + + Show postings and their running total. + +Flags: + --cumulative accumulation mode: show running total from report + start date (default) + -H --historical accumulation mode: show historical running + total/balance (includes postings before report + start date) + -A --average show running average of posting amounts instead + of total (implies --empty) + -m --match=DESC fuzzy search for one recent posting with + description closest to DESC + -r --related show postings' siblings instead + --invert display all amounts with reversed sign + --sort=FIELDS sort by: date, desc, account, amount, absamount, + or a comma-separated combination of these. For a + descending sort, prefix with -. (Default: date) + -w --width=N set output width (default: terminal width). -wN,M + sets description width as well. + --align-all guarantee alignment across all lines (slower) + --base-url=URLPREFIX in html output, generate links to hledger-web, + with this prefix. (Usually the base url shown by + hledger-web; can also be relative.) + -O --output-format=FMT select the output format. Supported formats: + txt, csv, tsv, html, fods, json. + -o --output-file=FILE write output to FILE. A file extension matching + one of the above formats selects that format. + + The register command displays matched postings, across all accounts, +in date order, with their running total or running historical balance. +(See also the 'aregister' command, which shows matched transactions in a +specific account.) + + register normally shows line per posting, but note that +multi-commodity amounts will occupy multiple lines (one line per +commodity). + + It is typically used with a query selecting a particular account, to +see that account's activity: + +$ hledger register checking +2008/01/01 income assets:bank:checking $1 $1 +2008/06/01 gift assets:bank:checking $1 $2 +2008/06/02 save assets:bank:checking $-1 $1 +2008/12/31 pay off assets:bank:checking $-1 0 + + With '--date2', it shows and sorts by secondary date instead. + + For performance reasons, column widths are chosen based on the first +1000 lines; this means unusually wide values in later lines can cause +visual discontinuities as column widths are adjusted. If you want to +ensure perfect alignment, at the cost of more time and memory, use the +'--align-all' flag. + + The '--historical'/'-H' flag adds the balance from any undisplayed +prior postings to the running total. This is useful when you want to +see only recent activity, with a historically accurate running balance: + +$ hledger register checking -b 2008/6 --historical +2008/06/01 gift assets:bank:checking $1 $2 +2008/06/02 save assets:bank:checking $-1 $1 +2008/12/31 pay off assets:bank:checking $-1 0 + + The '--depth' option limits the amount of sub-account detail +displayed. + + The '--average'/'-A' flag shows the running average posting amount +instead of the running total (so, the final number displayed is the +average for the whole report period). This flag implies '--empty' (see +below). It is affected by '--historical'. It works best when showing +just one account and one commodity. + + The '--related'/'-r' flag shows the _other_ postings in the +transactions of the postings which would normally be shown. + + The '--invert' flag negates all amounts. For example, it can be used +on an income account where amounts are normally displayed as negative +numbers. It's also useful to show postings on the checking account +together with the related account: + + The '--sort=FIELDS' flag sorts by the fields given, which can be any +of 'account', 'amount', 'absamount', 'date', or 'desc'/'description', +optionally separated by commas. For example, '--sort account,amount' +will group all transactions in each account, sorted by transaction +amount. Each field can be negated by a preceding '-', so '--sort +-amount' will show transactions ordered from smallest amount to largest +amount. + +$ hledger register --related --invert assets:checking + + With a reporting interval, register shows summary postings, one per +interval, aggregating the postings to each account: + +$ hledger register --monthly income +2008/01 income:salary $-1 $-1 +2008/06 income:gifts $-1 $-2 + + Periods with no activity, and summary postings with a zero amount, +are not shown by default; use the '--empty'/'-E' flag to see them: + +$ hledger register --monthly income -E +2008/01 income:salary $-1 $-1 +2008/02 0 $-1 +2008/03 0 $-1 +2008/04 0 $-1 +2008/05 0 $-1 +2008/06 income:gifts $-1 $-2 +2008/07 0 $-2 +2008/08 0 $-2 +2008/09 0 $-2 +2008/10 0 $-2 +2008/11 0 $-2 +2008/12 0 $-2 + + Often, you'll want to see just one line per interval. The '--depth' +option helps with this, causing subaccounts to be aggregated: + +$ hledger register --monthly assets --depth 1 +2008/01 assets $1 $1 +2008/06 assets $-1 0 +2008/12 assets $-1 $-1 + + Note when using report intervals, if you specify start/end dates +these will be adjusted outward if necessary to contain a whole number of +intervals. This ensures that the first and last intervals are full +length and comparable to the others in the report. + + With '-m DESC'/'--match=DESC', register does a fuzzy search for one +recent posting whose description is most similar to DESC. DESC should +contain at least two characters. If there is no similar-enough match, +no posting will be shown and the program exit code will be non-zero. + +* Menu: + +* Custom register output:: + + +File: hledger.info, Node: Custom register output, Up: register + +28.3.1 Custom register output +----------------------------- + +register normally uses the full terminal width (or 80 columns if it +can't detect that). You can override this with the '--width'/'-w' +option. + + The description and account columns normally share the space equally +(about half of (width - 40) each). You can adjust this by adding a +description width as part of -width's argument, comma-separated: +'--width W,D' . Here's a diagram (won't display correctly in -help): + +<--------------------------------- width (W) ----------------------------------> +date (10) description (D) account (W-41-D) amount (12) balance (12) +DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA + + and some examples: + +$ hledger reg # use terminal width (or 80 on windows) +$ hledger reg -w 100 # use width 100 +$ hledger reg -w 100,40 # set overall width 100, description width 40 + + This command also supports the output destination and output format +options The output formats supported are 'txt', 'csv', 'tsv' (_Added in +1.32_), and 'json'. + + +File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: register, Up: Standard report commands + +28.4 balancesheet +================= + +(bs) + + Show the end balances in asset and liability accounts. Amounts are +shown with normal positive sign, as in conventional financial +statements. + +Flags: + --sum calculation mode: show sum of posting amounts + (default) + --valuechange calculation mode: show total change of value of + period-end historical balances (caused by deposits, + withdrawals, market price fluctuations) + --gain calculation mode: show unrealised capital + gain/loss (historical balance value minus cost + basis) + --count calculation mode: show the count of postings + --change accumulation mode: accumulate amounts from column + start to column end (in multicolumn reports) + --cumulative accumulation mode: accumulate amounts from report + start (specified by e.g. -b/--begin) to column end + -H --historical accumulation mode: accumulate amounts from + journal start to column end (includes postings + before report start date) (default) + -l --flat list/tree mode: show accounts as a flat list + (default). Amounts exclude subaccount amounts, + except where the account is depth-clipped. + -t --tree list/tree mode: show accounts as a tree. Amounts + include subaccount amounts. + --drop=N in list mode, omit N leading account name parts + --declared include non-parent declared accounts (best used + with -E) + -A --average show a row average column (in multicolumn + reports) + -T --row-total show a row total column (in multicolumn reports) + --summary-only display only row summaries (e.g. row total, + average) (in multicolumn reports) + -N --no-total omit the final total row + --no-elide in tree mode, don't squash boring parent accounts + --format=FORMATSTR use this custom line format (in simple reports) + -S --sort-amount sort by amount instead of account code/name + -% --percent express values in percentage of each column's + total + --layout=ARG how to show multi-commodity amounts: + 'wide[,WIDTH]': all commodities on one line + 'tall' : each commodity on a new line + 'bare' : bare numbers, symbols in a column + --base-url=URLPREFIX in html output, generate hyperlinks to + hledger-web, with this prefix. (Usually the base + url shown by hledger-web; can also be relative.) + -O --output-format=FMT select the output format. Supported formats: + txt, html, csv, tsv, json. + -o --output-file=FILE write output to FILE. A file extension matching + one of the above formats selects that format. + + This command displays a balance sheet, showing historical ending +balances of asset and liability accounts. (To see equity as well, use +the balancesheetequity command.) + + Accounts declared with the 'Asset', 'Cash' or 'Liability' type are +shown (see account types). Or if no such accounts are declared, it +shows top-level accounts named 'asset' or 'liability' (case insensitive, +plurals allowed) and their subaccounts. + + Example: + +$ hledger balancesheet +Balance Sheet 2008-12-31 + + || 2008-12-31 +====================++============ + Assets || +--------------------++------------ + assets:bank:saving || $1 + assets:cash || $-2 +--------------------++------------ + || $-1 +====================++============ + Liabilities || +--------------------++------------ + liabilities:debts || $-1 +--------------------++------------ + || $-1 +====================++============ + Net: || 0 + + This command is a higher-level variant of the 'balance' command, and +supports many of that command's features, such as multi-period reports. +It is similar to 'hledger balance -H assets liabilities', but with +smarter account detection, and liabilities displayed with their sign +flipped. + + This command also supports the output destination and output format +options The output formats supported are 'txt', 'csv', 'tsv' (_Added in +1.32_), 'html', and 'json'. + + +File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: Standard report commands + +28.5 balancesheetequity +======================= + +(bse) + + This command displays a balance sheet, showing historical ending +balances of asset, liability and equity accounts. Amounts are shown +with normal positive sign, as in conventional financial statements. + +Flags: + --sum calculation mode: show sum of posting amounts + (default) + --valuechange calculation mode: show total change of value of + period-end historical balances (caused by deposits, + withdrawals, market price fluctuations) + --gain calculation mode: show unrealised capital + gain/loss (historical balance value minus cost + basis) + --count calculation mode: show the count of postings + --change accumulation mode: accumulate amounts from column + start to column end (in multicolumn reports) + --cumulative accumulation mode: accumulate amounts from report + start (specified by e.g. -b/--begin) to column end + -H --historical accumulation mode: accumulate amounts from + journal start to column end (includes postings + before report start date) (default) + -l --flat list/tree mode: show accounts as a flat list + (default). Amounts exclude subaccount amounts, + except where the account is depth-clipped. + -t --tree list/tree mode: show accounts as a tree. Amounts + include subaccount amounts. + --drop=N in list mode, omit N leading account name parts + --declared include non-parent declared accounts (best used + with -E) + -A --average show a row average column (in multicolumn + reports) + -T --row-total show a row total column (in multicolumn reports) + --summary-only display only row summaries (e.g. row total, + average) (in multicolumn reports) + -N --no-total omit the final total row + --no-elide in tree mode, don't squash boring parent accounts + --format=FORMATSTR use this custom line format (in simple reports) + -S --sort-amount sort by amount instead of account code/name + -% --percent express values in percentage of each column's + total + --layout=ARG how to show multi-commodity amounts: + 'wide[,WIDTH]': all commodities on one line + 'tall' : each commodity on a new line + 'bare' : bare numbers, symbols in a column + --base-url=URLPREFIX in html output, generate hyperlinks to + hledger-web, with this prefix. (Usually the base + url shown by hledger-web; can also be relative.) + -O --output-format=FMT select the output format. Supported formats: + txt, html, csv, tsv, json. + -o --output-file=FILE write output to FILE. A file extension matching + one of the above formats selects that format. + + This report shows accounts declared with the 'Asset', 'Cash', +'Liability' or 'Equity' type (see account types). Or if no such +accounts are declared, it shows top-level accounts named 'asset', +'liability' or 'equity' (case insensitive, plurals allowed) and their +subaccounts. + + Example: + +$ hledger balancesheetequity +Balance Sheet With Equity 2008-12-31 + + || 2008-12-31 +====================++============ + Assets || +--------------------++------------ + assets:bank:saving || $1 + assets:cash || $-2 +--------------------++------------ + || $-1 +====================++============ + Liabilities || +--------------------++------------ + liabilities:debts || $-1 +--------------------++------------ + || $-1 +====================++============ + Equity || +--------------------++------------ +--------------------++------------ + || 0 +====================++============ + Net: || 0 + + This command is a higher-level variant of the 'balance' command, and +supports many of that command's features, such as multi-period reports. +It is similar to 'hledger balance -H assets liabilities equity', but +with smarter account detection, and liabilities/equity displayed with +their sign flipped. + + This report is the easiest way to see if the accounting equation +(A+L+E = 0) is satisfied (after you have done a 'close --retain' to +merge revenues and expenses with equity, and perhaps added +'--infer-equity' to balance your commodity conversions). + + This command also supports the output destination and output format +options The output formats supported are 'txt', 'csv', 'tsv', 'html', +and 'json'. + + +File: hledger.info, Node: cashflow, Next: incomestatement, Prev: balancesheetequity, Up: Standard report commands + +28.6 cashflow +============= + +(cf) + + This command displays a (simple) cashflow statement, showing the +inflows and outflows affecting "cash" (ie, liquid, easily convertible) +assets. Amounts are shown with normal positive sign, as in conventional +financial statements. + +Flags: + --sum calculation mode: show sum of posting amounts + (default) + --valuechange calculation mode: show total change of value of + period-end historical balances (caused by deposits, + withdrawals, market price fluctuations) + --gain calculation mode: show unrealised capital + gain/loss (historical balance value minus cost + basis) + --count calculation mode: show the count of postings + --change accumulation mode: accumulate amounts from column + start to column end (in multicolumn reports) + (default) + --cumulative accumulation mode: accumulate amounts from report + start (specified by e.g. -b/--begin) to column end + -H --historical accumulation mode: accumulate amounts from + journal start to column end (includes postings + before report start date) + -l --flat list/tree mode: show accounts as a flat list + (default). Amounts exclude subaccount amounts, + except where the account is depth-clipped. + -t --tree list/tree mode: show accounts as a tree. Amounts + include subaccount amounts. + --drop=N in list mode, omit N leading account name parts + --declared include non-parent declared accounts (best used + with -E) + -A --average show a row average column (in multicolumn + reports) + -T --row-total show a row total column (in multicolumn reports) + --summary-only display only row summaries (e.g. row total, + average) (in multicolumn reports) + -N --no-total omit the final total row + --no-elide in tree mode, don't squash boring parent accounts + --format=FORMATSTR use this custom line format (in simple reports) + -S --sort-amount sort by amount instead of account code/name + -% --percent express values in percentage of each column's + total + --layout=ARG how to show multi-commodity amounts: + 'wide[,WIDTH]': all commodities on one line + 'tall' : each commodity on a new line + 'bare' : bare numbers, symbols in a column + --base-url=URLPREFIX in html output, generate hyperlinks to + hledger-web, with this prefix. (Usually the base + url shown by hledger-web; can also be relative.) + -O --output-format=FMT select the output format. Supported formats: + txt, html, csv, tsv, json. + -o --output-file=FILE write output to FILE. A file extension matching + one of the above formats selects that format. + + This report shows accounts declared with the 'Cash' type (see account +types). Or if no such accounts are declared, it shows accounts + + * under a top-level account named 'asset' (case insensitive, plural + allowed) + * whose name contains some variation of 'cash', 'bank', 'checking' or + 'saving'. + + More precisely: all accounts matching this case insensitive regular +expression: + + '^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$)' + + and their subaccounts. + + An example cashflow report: + +$ hledger cashflow +Cashflow Statement 2008 + + || 2008 +====================++====== + Cash flows || +--------------------++------ + assets:bank:saving || $1 + assets:cash || $-2 +--------------------++------ + || $-1 + + This command is a higher-level variant of the 'balance' command, and +supports many of that command's features, such as multi-period reports. +It is similar to 'hledger balance assets not:fixed not:investment +not:receivable', but with smarter account detection. + + This command also supports the output destination and output format +options The output formats supported are 'txt', 'csv', 'tsv' (_Added in +1.32_), 'html', and 'json'. + + +File: hledger.info, Node: incomestatement, Prev: cashflow, Up: Standard report commands + +28.7 incomestatement +==================== + +(is) + + Show revenue inflows and expense outflows during the report period. +Amounts are shown with normal positive sign, as in conventional +financial statements. + +Flags: + --sum calculation mode: show sum of posting amounts + (default) + --valuechange calculation mode: show total change of value of + period-end historical balances (caused by deposits, + withdrawals, market price fluctuations) + --gain calculation mode: show unrealised capital + gain/loss (historical balance value minus cost + basis) + --count calculation mode: show the count of postings + --change accumulation mode: accumulate amounts from column + start to column end (in multicolumn reports) + (default) + --cumulative accumulation mode: accumulate amounts from report + start (specified by e.g. -b/--begin) to column end + -H --historical accumulation mode: accumulate amounts from + journal start to column end (includes postings + before report start date) + -l --flat list/tree mode: show accounts as a flat list + (default). Amounts exclude subaccount amounts, + except where the account is depth-clipped. + -t --tree list/tree mode: show accounts as a tree. Amounts + include subaccount amounts. + --drop=N in list mode, omit N leading account name parts + --declared include non-parent declared accounts (best used + with -E) + -A --average show a row average column (in multicolumn + reports) + -T --row-total show a row total column (in multicolumn reports) + --summary-only display only row summaries (e.g. row total, + average) (in multicolumn reports) + -N --no-total omit the final total row + --no-elide in tree mode, don't squash boring parent accounts + --format=FORMATSTR use this custom line format (in simple reports) + -S --sort-amount sort by amount instead of account code/name + -% --percent express values in percentage of each column's + total + --layout=ARG how to show multi-commodity amounts: + 'wide[,WIDTH]': all commodities on one line + 'tall' : each commodity on a new line + 'bare' : bare numbers, symbols in a column + --base-url=URLPREFIX in html output, generate hyperlinks to + hledger-web, with this prefix. (Usually the base + url shown by hledger-web; can also be relative.) + -O --output-format=FMT select the output format. Supported formats: + txt, html, csv, tsv, json. + -o --output-file=FILE write output to FILE. A file extension matching + one of the above formats selects that format. + + This command displays an income statement, showing revenues and +expenses during one or more periods. + + It shows accounts declared with the 'Revenue' or 'Expense' type (see +account types). Or if no such accounts are declared, it shows top-level +accounts named 'revenue' or 'income' or 'expense' (case insensitive, +plurals allowed) and their subaccounts. + + Example: + +$ hledger incomestatement +Income Statement 2008 + + || 2008 +===================++====== + Revenues || +-------------------++------ + income:gifts || $1 + income:salary || $1 +-------------------++------ + || $2 +===================++====== + Expenses || +-------------------++------ + expenses:food || $1 + expenses:supplies || $1 +-------------------++------ + || $2 +===================++====== + Net: || 0 + + This command is a higher-level variant of the 'balance' command, and +supports many of that command's features, such as multi-period reports. +It is similar to 'hledger balance '(revenues|income)' expenses', but +with smarter account detection, and revenues/income displayed with their +sign flipped. + + This command also supports the output destination and output format +options The output formats supported are 'txt', 'csv', 'tsv' (_Added in +1.32_), 'html', and 'json'. + + +File: hledger.info, Node: Advanced report commands, Next: Chart commands, Prev: Standard report commands, Up: Top + +29 Advanced report commands +*************************** + +* Menu: + +* balance:: +* roi:: + + +File: hledger.info, Node: balance, Next: roi, Up: Advanced report commands + +29.1 balance +============ + +(bal) + + A flexible, general purpose "summing" report that shows accounts with +some kind of numeric data. This can be balance changes per period, end +balances, budget performance, unrealised capital gains, etc. + +Flags: + --sum calculation mode: show sum of posting amounts + (default) + --valuechange calculation mode: show total change of value of + period-end historical balances (caused by deposits, + withdrawals, market price fluctuations) + --gain calculation mode: show unrealised capital + gain/loss (historical balance value minus cost + basis) + --budget[=DESCPAT] calculation mode: show sum of posting amounts + together with budget goals defined by periodic + transactions. With a DESCPAT argument (must be + separated by = not space), + use only periodic transactions with matching + description + (case insensitive substring match). + --count calculation mode: show the count of postings + --change accumulation mode: accumulate amounts from column + start to column end (in multicolumn reports, + default) + --cumulative accumulation mode: accumulate amounts from report + start (specified by e.g. -b/--begin) to column end + -H --historical accumulation mode: accumulate amounts from + journal start to column end (includes postings + before report start date) + -l --flat list/tree mode: show accounts as a flat list + (default). Amounts exclude subaccount amounts, + except where the account is depth-clipped. + -t --tree list/tree mode: show accounts as a tree. Amounts + include subaccount amounts. + --drop=N in list mode, omit N leading account name parts + --declared include non-parent declared accounts (best used + with -E) + -A --average show a row average column (in multicolumn + reports) + -T --row-total show a row total column (in multicolumn reports) + --summary-only display only row summaries (e.g. row total, + average) (in multicolumn reports) + -N --no-total omit the final total row + --no-elide in tree mode, don't squash boring parent accounts + --format=FORMATSTR use this custom line format (in simple reports) + -S --sort-amount sort by amount instead of account code/name (in + flat mode). With multiple columns, sorts by the row + total, or by row average if that is displayed. + -% --percent express values in percentage of each column's + total + -r --related show the other accounts transacted with, instead + --invert display all amounts with reversed sign + --transpose switch rows and columns (use vertical time axis) + --layout=ARG how to lay out multi-commodity amounts and the + overall table: + 'wide[,W]': commodities on same line, up to W wide + 'tall' : commodities on separate lines + 'bare' : commodity symbols in a separate column + 'tidy' : each data field in its own column + --base-url=URLPREFIX in html output, generate links to hledger-web, + with this prefix. (Usually the base url shown by + hledger-web; can also be relative.) + -O --output-format=FMT select the output format. Supported formats: + txt, html, csv, tsv, json, fods. + -o --output-file=FILE write output to FILE. A file extension matching + one of the above formats selects that format. + + 'balance' is one of hledger's oldest and most versatile commands, for +listing account balances, balance changes, values, value changes and +more, during one time period or many. Generally it shows a table, with +rows representing accounts, and columns representing periods. + + Note there are some variants of the 'balance' command with convenient +defaults, which are 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 modes:: +* Budget report:: +* Balance report layout:: +* Balance report output:: +* Some useful balance reports:: + + +File: hledger.info, Node: balance features, Next: Simple balance report, Up: balance + +29.1.1 balance features +----------------------- + +Here's a quick overview of the 'balance' command's features, followed by +more detailed descriptions and examples. Many of these work with the +other balance-like commands as well ('bs', 'cf', 'is'..). + + 'balance' can show.. + + * accounts as a list ('-l') or a tree ('-t') + * optionally depth-limited ('-[1-9]') + * sorted by declaration order and name, or by amount + + ..and their.. + + * balance changes (the default) + * or actual and planned balance changes ('--budget') + * or value of balance changes ('-V') + * or change of balance values ('--valuechange') + * or unrealised capital gain/loss ('--gain') + * or balance changes from sibling postings ('--related'/'-r') + * or postings count ('--count') + + ..in.. + + * one time period (the whole journal period by default) + * or multiple periods ('-D', '-W', '-M', '-Q', '-Y', '-p INTERVAL') + + ..either.. + + * per period (the default) + * or accumulated since report start date ('--cumulative') + * or accumulated since account creation ('--historical/-H') + + ..possibly converted to.. + + * cost ('--value=cost[,COMM]'/'--cost'/'-B') + * or market value, as of transaction dates ('--value=then[,COMM]') + * or at period ends ('--value=end[,COMM]') + * or now ('--value=now') + * or at some other date ('--value=YYYY-MM-DD') + + ..with.. + + * totals ('-T'), averages ('-A'), percentages ('-%'), inverted sign + ('--invert') + * rows and columns swapped ('--transpose') + * another field used as account name ('--pivot') + * custom-formatted line items (single-period reports only) + ('--format') + * commodities displayed on the same line or multiple lines + ('--layout') + + This command supports the output destination and output format +options, with output formats 'txt', 'csv', 'tsv' (_Added in 1.32_), +'json', and (multi-period reports only:) 'html', 'fods' (_Added in +1.40_). In 'txt' output in a colour-supporting terminal, negative +amounts are shown in red. + + +File: hledger.info, Node: Simple balance report, Next: Balance report line format, Prev: balance features, Up: balance + +29.1.2 Simple balance report +---------------------------- + +With no arguments, 'balance' shows a list of all accounts and their +change of balance - ie, the sum of posting amounts, both inflows and +outflows - during the entire period of the journal. ("Simple" here +means just one column of numbers, covering a single period. You can +also have multi-period reports, described later.) + + For real-world accounts, these numbers will normally be their end +balance at the end of the journal period; more on this below. + + Accounts are sorted by declaration order if any, and then +alphabetically by account name. For instance (using +examples/sample.journal): + +$ hledger -f examples/sample.journal bal + $1 assets:bank:saving + $-2 assets:cash + $1 expenses:food + $1 expenses:supplies + $-1 income:gifts + $-1 income:salary + $1 liabilities:debts +-------------------- + 0 + + Accounts with a zero balance (and no non-zero subaccounts, in tree +mode - see below) are hidden by default. Use '-E/--empty' to show them +(revealing 'assets:bank:checking' here): + +$ hledger -f examples/sample.journal bal -E + 0 assets:bank:checking + $1 assets:bank:saving + $-2 assets:cash + $1 expenses:food + $1 expenses:supplies + $-1 income:gifts + $-1 income:salary + $1 liabilities:debts +-------------------- + 0 + + The total of the amounts displayed is shown as the last line, unless +'-N'/'--no-total' is used. + + +File: hledger.info, Node: Balance report line format, Next: Filtered balance report, Prev: Simple balance report, Up: balance + +29.1.3 Balance report line format +--------------------------------- + +For single-period balance reports displayed in the terminal (only), you +can use '--format FMT' to customise the format and content of each line. +Eg: + +$ hledger -f examples/sample.journal balance --format "%20(account) %12(total)" + assets $-1 + bank:saving $1 + cash $-2 + expenses $2 + food $1 + supplies $1 + income $-2 + gifts $-1 + salary $-1 + liabilities:debts $1 +--------------------------------- + 0 + + The FMT format string specifies the formatting applied to each +account/balance pair. It may contain any suitable text, with data +fields interpolated like so: + + '%[MIN][.MAX](FIELDNAME)' + + * MIN pads with spaces to at least this width (optional) + + * MAX truncates at this width (optional) + + * FIELDNAME must be enclosed in parentheses, and can be one of: + + * 'depth_spacer' - a number of spaces equal to the account's + depth, or if MIN is specified, MIN * depth spaces. + * 'account' - the account's name + * 'total' - the account's balance/posted total, right justified + + Also, FMT can begin with an optional prefix to control how +multi-commodity amounts are rendered: + + * '%_' - render on multiple lines, bottom-aligned (the default) + * '%^' - render on multiple lines, top-aligned + * '%,' - render on one line, comma-separated + + There are some quirks. Eg in one-line mode, '%(depth_spacer)' has no +effect, instead '%(account)' has indentation built in. Experimentation +may be needed to get pleasing results. + + Some example formats: + + * '%(total)' - the account's total + * '%-20.20(account)' - the account's name, left justified, padded to + 20 characters and clipped at 20 characters + * '%,%-50(account) %25(total)' - account name padded to 50 + characters, total padded to 20 characters, with multiple + commodities rendered on one line + * '%20(total) %2(depth_spacer)%-(account)' - the default format for + the single-column balance report + + +File: hledger.info, Node: Filtered balance report, Next: List or tree mode, Prev: Balance report line format, Up: balance + +29.1.4 Filtered balance report +------------------------------ + +You can show fewer accounts, a different time period, totals from +cleared transactions only, etc. by using query arguments or options to +limit the postings being matched. Eg: + +$ hledger -f examples/sample.journal bal --cleared assets date:200806 + $-2 assets:cash +-------------------- + $-2 + + +File: hledger.info, Node: List or tree mode, Next: Depth limiting, Prev: Filtered balance report, Up: balance + +29.1.5 List or tree mode +------------------------ + +By default, or with '-l/--flat', accounts are shown as a flat list with +their full names visible, as in the examples above. + + With '-t/--tree', the account hierarchy is shown, with subaccounts' +"leaf" names indented below their parent: + +$ hledger -f examples/sample.journal balance + $-1 assets + $1 bank:saving + $-2 cash + $2 expenses + $1 food + $1 supplies + $-2 income + $-1 gifts + $-1 salary + $1 liabilities:debts +-------------------- + 0 + + Notes: + + * "Boring" accounts are combined with their subaccount for more + compact output, unless '--no-elide' is used. Boring accounts have + no balance of their own and just one subaccount (eg 'assets:bank' + and 'liabilities' above). + + * All balances shown are "inclusive", ie including the balances from + all subaccounts. Note this means some repetition in the output, + which requires explanation when sharing reports with + non-plaintextaccounting-users. A tree mode report's final total is + the sum of the top-level balances shown, not of all the balances + shown. + + * Each group of sibling accounts (ie, under a common parent) is + sorted separately. + + +File: hledger.info, Node: Depth limiting, Next: Dropping top-level accounts, Prev: List or tree mode, Up: balance + +29.1.6 Depth limiting +--------------------- + +With a 'depth:NUM' query, or '--depth NUM' option, or just '-NUM' (eg: +'-3') balance reports will show accounts only to the specified depth, +hiding the deeper subaccounts. This can be useful for getting an +overview without too much detail. + + Account balances at the depth limit always include the balances from +any deeper subaccounts (even in list mode). Eg, limiting to depth 1: + +$ hledger -f examples/sample.journal balance -1 + $-1 assets + $2 expenses + $-2 income + $1 liabilities +-------------------- + 0 + + +File: hledger.info, Node: Dropping top-level accounts, Next: Showing declared accounts, Prev: Depth limiting, Up: balance + +29.1.7 Dropping top-level accounts +---------------------------------- + +You can also hide one or more top-level account name parts, using +'--drop NUM'. This can be useful for hiding repetitive top-level +account names: + +$ hledger -f examples/sample.journal bal expenses --drop 1 + $1 food + $1 supplies +-------------------- + $2 + + +File: hledger.info, Node: Showing declared accounts, Next: Sorting by amount, Prev: Dropping top-level accounts, Up: balance + +29.1.8 Showing declared accounts +-------------------------------- + +With '--declared', accounts which have been declared with an account +directive will be included in the balance report, even if they have no +transactions. (Since they will have a zero balance, you will also need +'-E/--empty' to see them.) + + More precisely, _leaf_ declared accounts (with no subaccounts) will +be included, since those are usually the more useful in reports. + + The idea of this is to be able to see a useful "complete" balance +report, even when you don't have transactions in all of your declared +accounts yet. + + +File: hledger.info, Node: Sorting by amount, Next: Percentages, Prev: Showing declared accounts, Up: balance + +29.1.9 Sorting by amount +------------------------ + +With '-S/--sort-amount', accounts with the largest (most positive) +balances are shown first. Eg: 'hledger bal expenses -MAS' shows your +biggest averaged monthly expenses first. When more than one commodity +is present, they will be sorted by the alphabetically earliest commodity +first, and then by subsequent commodities (if an amount is missing a +commodity, it is treated as 0). + + Revenues and liability balances are typically negative, however, so +'-S' shows these in reverse order. To work around this, you can add +'--invert' to flip the signs. Or you could use one of the higher-level +balance reports ('bs', 'is'..), which flip the sign automatically (eg: +'hledger is -MAS'). + + +File: hledger.info, Node: Percentages, Next: Multi-period balance report, Prev: Sorting by amount, Up: balance + +29.1.10 Percentages +------------------- + +With '-%/--percent', balance reports show each account's value expressed +as a percentage of the (column) total. + + Note it is not useful to calculate percentages if the amounts in a +column have mixed signs. In this case, make a separate report for each +sign, eg: + +$ hledger bal -% amt:`>0` +$ hledger bal -% amt:`<0` + + Similarly, if the amounts in a column have mixed commodities, convert +them to one commodity with '-B', '-V', '-X' or '--value', or make a +separate report for each commodity: + +$ hledger bal -% cur:\\$ +$ hledger bal -% cur:€ + + +File: hledger.info, Node: Multi-period balance report, Next: Balance change end balance, Prev: Percentages, Up: balance + +29.1.11 Multi-period balance report +----------------------------------- + +With a report interval (set by the '-D/--daily', '-W/--weekly', +'-M/--monthly', '-Q/--quarterly', '-Y/--yearly', or '-p/--period' flag), +'balance' shows a tabular report, with columns representing successive +time periods (and a title): + +$ hledger -f examples/sample.journal bal --quarterly income expenses -E +Balance changes in 2008: + + || 2008q1 2008q2 2008q3 2008q4 +===================++================================= + expenses:food || 0 $1 0 0 + expenses:supplies || 0 $1 0 0 + income:gifts || 0 $-1 0 0 + income:salary || $-1 0 0 0 +-------------------++--------------------------------- + || $-1 $1 0 0 + + Notes: + + * The report's start/end dates will be expanded, if necessary, to + fully encompass the displayed subperiods (so that the first and + last subperiods have the same duration as the others). + * Leading and trailing periods (columns) containing all zeroes are + not shown, unless '-E/--empty' is used. + * Accounts (rows) containing all zeroes are not shown, unless + '-E/--empty' is used. + * Amounts with many commodities are shown in abbreviated form, unless + '--no-elide' is used. + * Average and/or total columns can be added with the '-A/--average' + and '-T/--row-total' flags. + * The '--transpose' flag can be used to exchange rows and columns. + * The '--pivot FIELD' option causes a different transaction field to + be used as "account name". See PIVOTING. + * The '--summary-only' flag ('--summary' also works) hides all but + the Total and Average columns (those should be enabled with + '--row-total' and '-A/--average'). + + Multi-period reports with many periods can be too wide for easy +viewing in the terminal. Here are some ways to handle that: + + * Hide the totals row with '-N/--no-total' + * Filter to a single currency with 'cur:' + * Convert to a single currency with '-V [--infer-market-price]' + * Use a more compact layout like '--layout=bare' + * Maximize the terminal window + * Reduce the terminal's font size + * View with a pager like less, eg: 'hledger bal -D --color=yes | less + -RS' + * Output as CSV and use a CSV viewer like visidata ('hledger bal -D + -O csv | vd -f csv'), Emacs' csv-mode ('M-x csv-mode, C-c C-a'), or + a spreadsheet ('hledger bal -D -o a.csv && open a.csv') + * Output as HTML and view with a browser: 'hledger bal -D -o a.html + && open a.html' + + +File: hledger.info, Node: Balance change end balance, Next: Balance report modes, Prev: Multi-period balance report, Up: balance + +29.1.12 Balance change, end balance +----------------------------------- + +It's important to be clear on the meaning of the numbers shown in +balance reports. Here is some terminology we use: + + A *_balance change_* is the net amount added to, or removed from, an +account during some period. + + An *_end balance_* is the amount accumulated in an account as of some +date (and some time, but hledger doesn't store that; assume end of day +in your timezone). It is the sum of previous balance changes. + + We call it a *_historical end balance_* if it includes all balance +changes since the account was created. For a real world account, this +means it will match the "historical record", eg the balances reported in +your bank statements or bank web UI. (If they are correct!) + + In general, balance changes are what you want to see when reviewing +revenues and expenses, and historical end balances are what you want to +see when reviewing or reconciling asset, liability and equity accounts. + + 'balance' shows balance changes by default. To see accurate +historical end balances: + + 1. Initialise account starting balances with an "opening balances" + transaction (a transfer from equity to the account), unless the + journal covers the account's full lifetime. + + 2. Include all of of the account's prior postings in the report, by + not specifying a report start date, or by using the + '-H/--historical' flag. ('-H' causes report start date to be + ignored when summing postings.) + + +File: hledger.info, Node: Balance report modes, Next: Budget report, Prev: Balance change end balance, Up: balance + +29.1.13 Balance report modes +---------------------------- + +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 [CALCULATIONMODE] [ACCUMULATIONMODE] [VALUATIONMODE] +...' + +* Menu: + +* Calculation mode:: +* Accumulation mode:: +* Valuation mode:: +* Combining balance report modes:: + + +File: hledger.info, Node: Calculation mode, Next: Accumulation mode, Up: Balance report modes + +29.1.13.1 Calculation mode +.......................... + +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 mode, Next: Valuation mode, Prev: Calculation mode, Up: Balance report modes + +29.1.13.2 Accumulation mode +........................... + +How amounts should accumulate across a report's subperiods/columns. +Another way to say it: which time period's postings should contribute to +each cell's calculation. It is one of: + + * '--change' : calculate with postings from column start to column + end, ie "just this column". Typically used to see + revenues/expenses. (*default for balance, cashflow, + incomestatement*) + + * '--cumulative' : calculate with postings from report start to + column end, ie "previous columns plus this column". Typically used + to show changes accumulated since the report's start date. Not + often used. + + * '--historical/-H' : calculate with postings from journal start to + column end, ie "all postings from before report start date until + this column's end". Typically used to see historical end balances + of assets/liabilities/equity. (*default for balancesheet, + balancesheetequity*) + + +File: hledger.info, Node: Valuation mode, Next: Combining balance report modes, Prev: Accumulation mode, Up: Balance report modes + +29.1.13.3 Valuation mode +........................ + +Which kind of value or cost conversion should be applied, if any, before +displaying the report. See Cost reporting and Value reporting for more +about conversions. + + A valuation (or cost) mode can be selected with the -value option: + + * no conversion : 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 with the legacy -B/-V/-X options, which are equivalent and easier +to type: + + * '-B'/'--cost' : like -value=cost + * '-V'/'--market' : like -value=end + * '-X COMM'/'--exchange COMM' : like -value=end,COMM + + Note that -value can also convert to cost, as a convenience; but +actually -cost and -value are independent options, and could be used +together. + + +File: hledger.info, Node: Combining balance report modes, Prev: Valuation mode, Up: Balance report modes + +29.1.13.4 Combining balance report modes +........................................ + +Most combinations of these modes 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 modes, Up: balance + +29.1.14 Budget report +--------------------- + +The '--budget' report is like a regular balance report, but with two +main differences: + + * Budget goals and performance percentages are also shown, in + brackets + * Accounts which don't have budget goals are hidden by default. + + This is useful for comparing planned and actual income, expenses, +time usage, etc. + + Periodic transaction rules are used to define budget goals. For +example, here's a periodic rule defining monthly goals for bus travel +and food expenses: + +;; Budget +~ monthly + (expenses:bus) $30 + (expenses:food) $400 + + After recording some actual expenses, + +;; Two months worth of expenses +2017-11-01 + income $-1950 + expenses:bus $35 + expenses:food:groceries $310 + expenses:food:dining $42 + expenses:movies $38 + assets:bank:checking + +2017-12-01 + income $-2100 + expenses:bus $53 + expenses:food:groceries $380 + expenses:food:dining $32 + expenses:gifts $100 + assets:bank:checking + + we can see a budget report like this: + +$ hledger bal -M --budget +Budget performance in 2017-11-01..2017-12-31: + + || Nov Dec +===============++============================================ + || $-425 $-565 + expenses || $425 [ 99% of $430] $565 [131% of $430] + expenses:bus || $35 [117% of $30] $53 [177% of $30] + expenses:food || $352 [ 88% of $400] $412 [103% of $400] +---------------++-------------------------------------------- + || 0 [ 0% of $430] 0 [ 0% of $430] + + This is "goal-based budgeting"; you define goals for accounts and +periods, often recurring, and hledger shows performance relative to the +goals. This contrasts with "envelope budgeting", which is more detailed +and strict - useful when cash is tight, but also quite a bit more work. +https://plaintextaccounting.org/Budgeting has more on this topic. + +* Menu: + +* Using the budget report:: +* Budget date surprises:: +* Selecting budget goals:: +* Budgeting vs forecasting:: + + +File: hledger.info, Node: Using the budget report, Next: Budget date surprises, Up: Budget report + +29.1.14.1 Using the budget report +................................. + +Historically this report has been confusing and fragile. hledger's +version should be relatively robust and intuitive, but you may still +find surprises. Here are more notes to help with learning and +troubleshooting. + + * In the above example, 'expenses:bus' and 'expenses:food' are shown + because they have budget goals during the report period. + + * Their parent 'expenses' is also shown, with budget goals aggregated + from the children. + + * The subaccounts 'expenses:food:groceries' and + 'expenses:food:dining' are not shown since they have no budget goal + of their own, but they contribute to 'expenses:food''s actual + amount. + + * Unbudgeted accounts 'expenses:movies' and 'expenses:gifts' are also + not shown, but they contribute to 'expenses''s actual amount. + + * The other unbudgeted accounts 'income' and 'assets:bank:checking' + are grouped as ''. + + * '--depth' or 'depth:' can be used to limit report depth in the + usual way (but will not reveal unbudgeted subaccounts). + + * Amounts are always inclusive of subaccounts (even in '-l/--list' + mode). + + * Numbers displayed in a -budget report will not always agree with + the totals, because of hidden unbudgeted accounts; this is normal. + '-E/--empty' can be used to reveal the hidden accounts. + + * In the periodic rules used for setting budget goals, unbalanced + postings are convenient. + + * You can filter budget reports with the usual queries, eg to focus + on particular accounts. It's common to restrict them to just + expenses. (The '' account is occasionally hard to + exclude; this is because of date surprises, discussed below.) + + * When you have multiple currencies, you may want to convert them to + one ('-X COMM --infer-market-prices') and/or show just one at a + time ('cur:COMM'). If you do need to show multiple currencies at + once, '--layout bare' can be helpful. + + * You can "roll over" amounts (actual and budgeted) to the next + period with '--cumulative'. + + See also: https://hledger.org/budgeting.html. + + +File: hledger.info, Node: Budget date surprises, Next: Selecting budget goals, Prev: Using the budget report, Up: Budget report + +29.1.14.2 Budget date surprises +............................... + +With small data, or when starting out, some of the generated budget goal +transaction dates might fall outside the report periods. Eg with the +following journal and report, the first period appears to have no +'expenses:food' budget. (Also the '' account should be +excluded by the 'expenses' query, but isn't.): + +~ monthly in 2020 + (expenses:food) $500 + +2020-01-15 + expenses:food $400 + assets:checking + +$ hledger bal --budget expenses +Budget performance in 2020-01-15: + + || 2020-01-15 +===============++==================== + || $400 + expenses:food || 0 [ 0% of $500] +---------------++-------------------- + || $400 [80% of $500] + + In this case, the budget goal transactions are generated on first +days of of month (this can be seen with 'hledger print --forecast +tag:generated expenses'). Whereas the report period defaults to just +the 15th day of january (this can be seen from the report table's column +headings). + + To fix this kind of thing, be more explicit about the report period +(and/or the periodic rules' dates). In this case, adding '-b 2020' does +the trick. + + +File: hledger.info, Node: Selecting budget goals, Next: Budgeting vs forecasting, Prev: Budget date surprises, Up: Budget report + +29.1.14.3 Selecting budget goals +................................ + +By default, the budget report uses all available periodic transaction +rules to generate goals. This includes rules with a different report +interval from your report. Eg if you have daily, weekly and monthly +periodic rules, all of these will contribute to the goals in a monthly +budget report. + + You can select a subset of periodic rules by providing an argument to +the '--budget' flag. '--budget=DESCPAT' will match all periodic rules +whose description contains DESCPAT, a case-insensitive substring (not a +regular expression or query). This means you can give your periodic +rules descriptions (remember that two spaces are needed between period +expression and description), and then select from multiple budgets +defined in your journal. + + +File: hledger.info, Node: Budgeting vs forecasting, Prev: Selecting budget goals, Up: Budget report + +29.1.14.4 Budgeting vs forecasting +.................................. + +'--forecast' and '--budget' both use the periodic transaction rules in +the journal to generate temporary transactions for reporting purposes. +However they are separate features - though you can use both at the same +time if you want. Here are some differences between them: + +-forecast -budget +-------------------------------------------------------------------------- +is a general option; it enables is a balance command option; +forecasting with all reports it selects the balance + report's budget mode +generates visible transactions which generates invisible +appear in reports transactions which produce + goal amounts +generates forecast transactions from generates budget goal +after the last regular transaction, to transactions throughout the +the end of the report period; or with report period, optionally +an argument '--forecast=PERIODEXPR' restricted by periods +generates them throughout the specified in the periodic +specified period, both optionally transaction rules +restricted by periods specified in the +periodic transaction rules +uses all periodic rules uses all periodic rules; or + with an argument + '--budget=DESCPAT' uses just + the rules matched by DESCPAT + + +File: hledger.info, Node: Balance report layout, Next: Balance report output, Prev: Budget report, Up: balance + +29.1.15 Balance report layout +----------------------------- + +The '--layout' option affects how 'balance' and the other balance-like +commands show multi-commodity amounts and commodity symbols. It can +improve readability, for humans and/or machines (other software). It +has four possible values: + + * '--layout=wide[,WIDTH]': commodities are shown on a single line, + optionally elided to WIDTH + * '--layout=tall': each commodity is shown on a separate line + * '--layout=bare': commodity symbols are in their own column, amounts + are bare numbers + * '--layout=tidy': data is normalised to easily-consumed "tidy" form, + with one row per data value. (This one is currently supported only + by the 'balance' command.) + + Here are the '--layout' modes supported by each output format Only +CSV output supports all of them: + +- txt csv html json sql +--------------------------------------- +wide Y Y Y +tall Y Y Y +bare Y Y Y +tidy Y + + Examples: + +* Menu: + +* Wide layout:: +* Tall layout:: +* Bare layout:: +* Tidy layout:: + + +File: hledger.info, Node: Wide layout, Next: Tall layout, Up: Balance report layout + +29.1.15.1 Wide layout +..................... + +With many commodities, reports can be very wide: + +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide +Balance changes in 2012-01-01..2014-12-31: + + || 2012 2013 2014 Total +==================++==================================================================================================================================================================================================================== + Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT +------------------++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT + + A width limit reduces the width, but some commodities will be hidden: + +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32 +Balance changes in 2012-01-01..2014-12-31: + + || 2012 2013 2014 Total +==================++=========================================================================================================================== + Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. +------------------++--------------------------------------------------------------------------------------------------------------------------- + || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. + + +File: hledger.info, Node: Tall layout, Next: Bare layout, Prev: Wide layout, Up: Balance report layout + +29.1.15.2 Tall layout +..................... + +Each commodity gets a new line (may be different in each column), and +account names are repeated: + +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall +Balance changes in 2012-01-01..2014-12-31: + + || 2012 2013 2014 Total +==================++================================================== + Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + Assets:US:ETrade || 18.00 VHT 294.00 VHT +------------------++-------------------------------------------------- + || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + || 18.00 VHT 294.00 VHT + + +File: hledger.info, Node: Bare layout, Next: Tidy layout, Prev: Tall layout, Up: Balance report layout + +29.1.15.3 Bare layout +..................... + +Commodity symbols are kept in one column, each commodity has its own +row, amounts are bare numbers, account names are repeated: + +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare +Balance changes in 2012-01-01..2014-12-31: + + || Commodity 2012 2013 2014 Total +==================++============================================= + Assets:US:ETrade || GLD 0 70.00 0 70.00 + Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 + Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 + Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 + Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 +------------------++--------------------------------------------- + || GLD 0 70.00 0 70.00 + || ITOT 10.00 18.00 -11.00 17.00 + || USD 337.18 -98.12 4881.44 5120.50 + || VEA 12.00 10.00 14.00 36.00 + || VHT 106.00 18.00 170.00 294.00 + + Bare layout also affects CSV output, which is useful for producing +data that is easier to consume, eg for making charts: + +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare +"account","commodity","balance" +"Assets:US:ETrade","GLD","70.00" +"Assets:US:ETrade","ITOT","17.00" +"Assets:US:ETrade","USD","5120.50" +"Assets:US:ETrade","VEA","36.00" +"Assets:US:ETrade","VHT","294.00" +"Total:","GLD","70.00" +"Total:","ITOT","17.00" +"Total:","USD","5120.50" +"Total:","VEA","36.00" +"Total:","VHT","294.00" + + Bare layout will sometimes display an extra row for the no-symbol +commodity, because of zero amounts (hledger treats zeroes as +commodity-less, usually). This can break 'hledger-bar' confusingly +(workaround: add a 'cur:' query to exclude the no-symbol row). + + +File: hledger.info, Node: Tidy layout, Prev: Bare layout, Up: Balance report layout + +29.1.15.4 Tidy layout +..................... + +This produces normalised "tidy data" (see +https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html) +where every variable has its own column and each row represents a single +data point. This is the easiest kind of data for other software to +consume: + +$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy +"account","period","start_date","end_date","commodity","value" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" +"Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" +"Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" +"Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" + + +File: hledger.info, Node: Balance report output, Next: Some useful balance reports, Prev: Balance report layout, Up: balance + +29.1.16 Balance report output +----------------------------- + +As noted in Output format, if you choose HTML output (by using '-O html' +or '-o somefile.html'), you can create a 'hledger.css' file in the same +directory to customise the report's appearance. + + The HTML and FODS output formats can generate hyperlinks to a +'hledger-web' register view for each account and period. E.g. if your +'hledger-web' server is reachable at 'http://localhost:5000' then you +might run the 'balance' command with the extra option +'--base-url=http://localhost:5000'. You can also produce relative +links, like '--base-url="some/path"' or '--base-url=""'.) + + +File: hledger.info, Node: Some useful balance reports, Prev: Balance report output, Up: balance + +29.1.17 Some useful balance reports +----------------------------------- + +Some frequently used 'balance' options/reports are: + + * 'bal -M revenues expenses' + Show revenues/expenses in each month. Also available as the + 'incomestatement' command. + + * 'bal -M -H assets liabilities' + Show historical asset/liability balances at each month end. Also + available as the 'balancesheet' command. + + * 'bal -M -H assets liabilities equity' + Show historical asset/liability/equity balances at each month end. + Also available as the 'balancesheetequity' command. + + * 'bal -M assets not:receivable' + Show changes to liquid assets in each month. Also available as the + 'cashflow' command. + + Also: + + * 'bal -M expenses -2 -SA' + Show monthly expenses summarised to depth 2 and sorted by average + amount. + + * 'bal -M --budget expenses' + Show monthly expenses and budget goals. + + * 'bal -M --valuechange investments' + Show monthly change in market value of investment assets. + + * 'bal investments --valuechange -D date:lastweek amt:'>1000' -STA + [--invert]' + Show top gainers [or losers] last week + + +File: hledger.info, Node: roi, Prev: balance, Up: Advanced report commands + +29.2 roi +======== + +Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on +your investments. + +Flags: + --cashflow show all amounts that were used to compute + returns + --investment=QUERY query to select your investment transactions + --profit-loss=QUERY --pnl query to select profit-and-loss or + appreciation/valuation transactions + + At a minimum, you need to supply a query (which could be just an +account name) to select your investment(s) with '--inv', and another +query to identify your profit and loss transactions with '--pnl'. + + If you do not record changes in the value of your investment +manually, or do not require computation of time-weighted return (TWR), +'--pnl' could be an empty query ('--pnl ""' or '--pnl STR' where 'STR' +does not match any of your accounts). + + This command will compute and display the internalized rate of return +(IRR, also known as money-weighted rate of return) and time-weighted +rate of return (TWR) for your investments for the time period requested. +IRR is always annualized due to the way it is computed, but TWR is +reported both as a rate over the chosen reporting period and as an +annual rate. + + Price directives will be taken into account if you supply appropriate +'--cost' or '--value' flags (see VALUATION). + + Note, in some cases this report can fail, for these reasons: + + * Error (NotBracketed): No solution for Internal Rate of Return + (IRR). Possible causes: IRR is huge (>1000000%), balance of + investment becomes negative at some point in time. + * Error (SearchFailed): Failed to find solution for Internal Rate of + Return (IRR). Either search does not converge to a solution, or + converges too slowly. + + Examples: + + * Using roi to compute total return of investment in stocks: + https://github.com/simonmichael/hledger/blob/master/examples/investing/roi-unrealised.ledger + + * Cookbook > Return on Investment: https://hledger.org/roi.html + +* Menu: + +* Spaces and special characters in --inv and --pnl:: +* Semantics of --inv and --pnl:: +* IRR and TWR explained:: + + +File: hledger.info, Node: Spaces and special characters in --inv and --pnl, Next: Semantics of --inv and --pnl, Up: roi + +29.2.1 Spaces and special characters in '--inv' and +--------------------------------------------------- + +'--pnl' Note that '--inv' and '--pnl''s argument is a query, and queries +could have several space-separated terms (see QUERIES). + + To indicate that all search terms form single command-line argument, +you will need to put them in quotes (see Special characters): + +$ hledger roi --inv 'term1 term2 term3 ...' + + If any query terms contain spaces themselves, you will need an extra +level of nested quoting, eg: + +$ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'" + + +File: hledger.info, Node: Semantics of --inv and --pnl, Next: IRR and TWR explained, Prev: Spaces and special characters in --inv and --pnl, Up: roi + +29.2.2 Semantics of '--inv' and '--pnl' +--------------------------------------- + +Query supplied to '--inv' has to match all transactions that are related +to your investment. Transactions not matching '--inv' will be ignored. + + In these transactions, ROI will conside postings that match '--inv' +to be "investment postings" and other postings (not matching '--inv') +will be sorted into two categories: "cash flow" and "profit and loss", +as ROI needs to know which part of the investment value is your +contributions and which is due to the return on investment. + + * "Cash flow" is depositing or withdrawing money, buying or selling + assets, or otherwise converting between your investment commodity + and any other commodity. Example: + + 2019-01-01 Investing in Snake Oil + assets:cash -$100 + investment:snake oil + + 2020-01-01 Selling my Snake Oil + assets:cash $10 + investment:snake oil = 0 + + * "Profit and loss" is change in the value of your investment: + + 2019-06-01 Snake Oil falls in value + investment:snake oil = $57 + equity:unrealized profit or loss + + All non-investment postings are assumed to be "cash flow", unless +they match '--pnl' query. Changes in value of your investment due to +"profit and loss" postings will be considered as part of your investment +return. + + Example: if you use '--inv snake --pnl equity:unrealized', then +postings in the example below would be classifed as: + +2019-01-01 Snake Oil #1 + assets:cash -$100 ; cash flow posting + investment:snake oil ; investment posting + +2019-03-01 Snake Oil #2 + equity:unrealized pnl -$100 ; profit and loss posting + snake oil ; investment posting + +2019-07-01 Snake Oil #3 + equity:unrealized pnl ; profit and loss posting + cash -$100 ; cash flow posting + snake oil $50 ; investment posting + + +File: hledger.info, Node: IRR and TWR explained, Prev: Semantics of --inv and --pnl, Up: roi + +29.2.3 IRR and TWR explained +---------------------------- + +"ROI" stands for "return on investment". Traditionally this was +computed as a difference between current value of investment and its +initial value, expressed in percentage of the initial value. + + However, this approach is only practical in simple cases, where +investments receives no in-flows or out-flows of money, and where rate +of growth is fixed over time. For more complex scenarios you need +different ways to compute rate of return, and this command implements +two of them: IRR and TWR. + + Internal rate of return, or "IRR" (also called "money-weighted rate +of return") takes into account effects of in-flows and out-flows, and +the time between them. Investment at a particular fixed interest rate +is going to give you more interest than the same amount invested at the +same interest rate, but made later in time. If you are withdrawing from +your investment, your future gains would be smaller (in absolute +numbers), and will be a smaller percentage of your initial investment, +so your IRR will be smaller. And if you are adding to your investment, +you will receive bigger absolute gains, which will be a bigger +percentage of your initial investment, so your IRR will be larger. + + As mentioned before, in-flows and out-flows would be any cash that +you personally put in or withdraw, and for the "roi" command, these are +the postings that match the query in the'--inv' argument and NOT match +the query in the'--pnl' argument. + + If you manually record changes in the value of your investment as +transactions that balance them against "profit and loss" (or "unrealized +gains") account or use price directives, then in order for IRR to +compute the precise effect of your in-flows and out-flows on the rate of +return, you will need to record the value of your investement on or +close to the days when in- or out-flows occur. + + In technical terms, IRR uses the same approach as computation of net +present value, and tries to find a discount rate that makes net present +value of all the cash flows of your investment to add up to zero. This +could be hard to wrap your head around, especially if you haven't done +discounted cash flow analysis before. Implementation of IRR in hledger +should produce results that match the '=XIRR' formula in Excel. + + Second way to compute rate of return that 'roi' command implements is +called "time-weighted rate of return" or "TWR". Like IRR, it will +account for the effect of your in-flows and out-flows, but unlike IRR it +will try to compute the true rate of return of the underlying asset, +compensating for the effect that deposits and withdrawas have on the +apparent rate of growth of your investment. + + TWR represents your investment as an imaginary "unit fund" where +in-flows/ out-flows lead to buying or selling "units" of your investment +and changes in its value change the value of "investment unit". Change +in "unit price" over the reporting period gives you rate of return of +your investment, and make TWR less sensitive than IRR to the effects of +cash in-flows and out-flows. + + References: + + * Explanation of rate of return + * Explanation of IRR + * Explanation of TWR + * IRR vs TWR + * Examples of computing IRR and TWR and discussion of the limitations + of both metrics + + +File: hledger.info, Node: Chart commands, Next: Data generation commands, Prev: Advanced report commands, Up: Top + +30 Chart commands +***************** + +* Menu: + +* activity:: + + +File: hledger.info, Node: activity, Up: Chart commands + +30.1 activity +============= + +Show an ascii barchart of posting counts per interval. + +Flags: +no command-specific flags + + The activity command displays an ascii histogram showing transaction +counts by day, week, month or other reporting interval (by day is the +default). With query arguments, it counts only matched transactions. + + Examples: + +$ hledger activity --quarterly +2008-01-01 ** +2008-04-01 ******* +2008-07-01 +2008-10-01 ** + + +File: hledger.info, Node: Data generation commands, Next: Maintenance commands, Prev: Chart commands, Up: Top + +31 Data generation commands +*************************** + +* Menu: + +* close:: +* rewrite:: + + +File: hledger.info, Node: close, Next: rewrite, Up: Data generation commands + +31.1 close +========== + +(equity) + + 'close' prints several kinds of "closing" and/or "opening" +transactions, useful in various situations: migrating balances to a new +journal file, retaining earnings into equity, consolidating balances, +viewing lot costs.. Like 'print', it prints valid journal entries. You +can copy these into your journal file(s) when you are happy with how +they look. + +Flags: + --clopen[=TAGVAL] show closing and opening balances transactions, + for AL accounts by default + --close[=TAGVAL] show just a closing balances transaction + --open[=TAGVAL] show just an opening balances transaction + --assert[=TAGVAL] show a balance assertions transaction + --assign[=TAGVAL] show a balance assignments transaction + --retain[=TAGVAL] show a retain earnings transaction, for RX + accounts by default + -x --explicit show all amounts explicitly + --show-costs show amounts with different costs separately + --interleaved show source and destination postings together + --assertion-type=TYPE =, ==, =* or ==* + --close-desc=DESC set closing transaction's description + --close-acct=ACCT set closing transaction's destination account + --open-desc=DESC set opening transaction's description + --open-acct=ACCT set opening transaction's source account + --round=TYPE how much rounding or padding should be done when + displaying amounts ? + none - show original decimal digits, + as in journal (default) + soft - just add or remove decimal zeros + to match precision + hard - round posting amounts to precision + (can unbalance transactions) + all - also round cost amounts to precision + (can unbalance transactions) + + 'close' has six modes, selected by choosing one of the mode flags: +'--clopen', '--close' (default), '--open', '--assert', '--assign', or +'--retain'. They are all doing the same kind of operation, but with +different defaults for different situations. + + The journal entries generated by 'close' will have a 'clopen:' tag, +which is helpful when you want to exclude them from reports. If the +main journal file name contains a number, the tag's value will be that +base file name with the number incremented. Eg if the journal file is +2025.journal, the tag will be 'clopen:2026'. Or you can set the tag +value by providing an argument to the mode flag. Eg '--close=foo' or +'--clopen=2025-main'. + +* Menu: + +* close --clopen:: +* close --close:: +* close --open:: +* close --assert:: +* close --assign:: +* close --retain:: +* close customisation:: +* close and balance assertions:: +* close examples:: + + +File: hledger.info, Node: close --clopen, Next: close --close, Up: close + +31.1.1 close -clopen +-------------------- + +This is useful if migrating balances to a new journal file at the start +of a new year. It prints a "closing balances" transaction that zeroes +out account balances (Asset and Liability accounts, by default), and an +opposite "opening balances" transaction that restores them again. +Typically, you would run + +hledger close --clopen -e NEWYEAR >> $LEDGER_FILE + + and then move the opening transaction from the old file to the new +file (and probably also update your LEDGER_FILE environment variable). + + Why might you do this ? If your reports are fast, you may not need +it. But at some point you will probably want to partition your data by +time, for performance or data integrity or regulatory reasons. A new +file or set of files per year is common. Then, having each file/fileset +"bookended" with opening and closing balance transactions will allow you +to freely pick and choose which files to read - just the current year, +any past year, any sequence of years, or all of them - while showing +correct account balances in each case. The earliest opening balances +transaction sets correct starting balances, and any later +closing/opening pairs will harmlessly cancel each other out. + + The balances will be transferred to and from 'equity:opening/closing +balances' by default. You can override this by using '--close-acct' +and/or '--open-acct'. + + You can select a different set of accounts to close/open by providing +an account query. Eg to add Equity accounts, provide arguments like +'assets liabilities equity' or 'type:ALE'. When migrating to a new +file, you'll usually want to bring along the AL or ALE accounts, but not +the RX accounts (Revenue, Expense). + + Assertions will be added indicating and checking the new balances of +the closed/opened accounts. + + +File: hledger.info, Node: close --close, Next: close --open, Prev: close --clopen, Up: close + +31.1.2 close -close +------------------- + +This prints just the closing balances transaction of '--clopen'. It is +the default if you don't specify a mode. + + More customisation options are described below. Among other things, +you can use 'close --close' to generate a transaction moving the +balances from any set of accounts, to a different account. (If you need +to move just a portion of the balance, see hledger-move.) + + +File: hledger.info, Node: close --open, Next: close --assert, Prev: close --close, Up: close + +31.1.3 close -open +------------------ + +This prints just the opening balances transaction of '--clopen'. (It is +similar to Ledger's equity command.) + + +File: hledger.info, Node: close --assert, Next: close --assign, Prev: close --open, Up: close + +31.1.4 close -assert +-------------------- + +This prints a transaction that asserts the account balances as they are +on the end date (and adds an 'assert:' tag). It could be useful as +documention and to guard against changes. + + +File: hledger.info, Node: close --assign, Next: close --retain, Prev: close --assert, Up: close + +31.1.5 close -assign +-------------------- + +This prints a transaction that assigns the account balances as they are +on the end date (and adds an "assign:" tag). Unlike balance assertions, +assignments will post changes to balances as needed to reach the +specified amounts. + + This is another way to set starting balances when migrating to a new +file, and it will set them correctly even in the presence of earlier +files which do not have a closing balances transaction. However, it can +hide errors, and disturb the accounting equation, so '--clopen' is +usually recommended. + + +File: hledger.info, Node: close --retain, Next: close customisation, Prev: close --assign, Up: close + +31.1.6 close -retain +-------------------- + +This is like '--close', but it closes Revenue and Expense account +balances by default. They will be transferred to 'equity:retained +earnings', or another account specified with '--close-acct'. + + Revenues and expenses correspond to changes in equity. They are +categorised separately for reporting purposes, but traditionally at the +end of each accounting period, businesses consolidate them into equity, +This is called "retaining earnings", or "closing the books". + + In personal accounting, there's not much reason to do this, and most +people don't. (One reason to do it is to help the 'balancesheetequity' +report show a zero total, demonstrating that the accounting equation +(A-L=E) is satisfied.) + + +File: hledger.info, Node: close customisation, Next: close and balance assertions, Prev: close --retain, Up: close + +31.1.7 close customisation +-------------------------- + +In all modes, the following things can be overridden: + + * the accounts to be closed/opened, with account query arguments + * the closing/opening dates, with '-e OPENDATE' + * the balancing account, with '--close-acct=ACCT' and/or + '--open-acct=ACCT' + * the transaction descriptions, with '--close-desc=DESC' and + '--open-desc=DESC' + * the transactions' 'clopen' tag value, with a 'TAGVAL' argument for + the mode flag (see above). + + By default, the closing date is yesterday, or the journal's end date, +whichever is later; and the opening date is always one day after the +closing date. You can change these by specifying a report end date; the +closing date will be the last day of the report period. Eg '-e 2024' +means "close on 2023-12-31, open on 2024-01-01". + + With '--x/--explicit', the balancing amount will be shown explicitly, +and if it involves multiple commodities, a separate posting will be +generated for each of them (similar to 'print -x'). + + With '--interleaved', each individual transfer is shown with source +and destination postings next to each other (perhaps useful for +troubleshooting). + + With '--show-costs', balances' costs are also shown, with different +costs kept separate. This may generate very large journal entries, if +you have many currency conversions or investment transactions. 'close +--show-costs' is currently the best way to view investment lots with +hledger. (To move or dispose of lots, see the more capable +'hledger-move' script.) + + +File: hledger.info, Node: close and balance assertions, Next: close examples, Prev: close customisation, Up: close + +31.1.8 close and balance assertions +----------------------------------- + +'close' adds balance assertions verifying that the accounts have been +reset to zero in a closing transaction or restored to their previous +balances in an opening transaction. These provide useful error +checking, but you can ignore them temporarily with '-I', or remove them +if you prefer. + + Single-commodity, subaccount-exclusive balance assertions ('=') are +generated by default. This can be changed with '--assertion-type='==*'' +(eg). + + When running 'close' you should probably avoid using '-C', '-R', +'status:' (filtering by status or realness) or '--auto' (generating +postings), since the generated balance assertions would then require +these. + + Transactions with multiple dates (eg posting dates) spanning the file +boundary also can disrupt the balance assertions: + +2023-12-30 a purchase made in december, cleared in january + expenses:food 5 + assets:bank:checking -5 ; date: 2023-01-02 + + To solve this you can transfer the money to and from a temporary +account, splitting the multi-day transaction into two single-day +transactions: + +; in 2022.journal: +2022-12-30 a purchase made in december, cleared in january + expenses:food 5 + equity:pending -5 + +; in 2023.journal: +2023-01-02 last year's transaction cleared + equity:pending 5 = 0 + assets:bank:checking -5 + + +File: hledger.info, Node: close examples, Prev: close and balance assertions, Up: close + +31.1.9 close examples +--------------------- + +* Menu: + +* Retain earnings:: +* Migrate balances to a new file:: +* More detailed close examples:: + + +File: hledger.info, Node: Retain earnings, Next: Migrate balances to a new file, Up: close examples + +31.1.9.1 Retain earnings +........................ + +Record 2022's revenues/expenses as retained earnings on 2022-12-31, +appending the generated transaction to the journal: + +$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal + + After this, to see 2022's revenues and expenses you must exclude the +retain earnings transaction: + +$ hledger -f 2022.journal is not:desc:'retain earnings' + + +File: hledger.info, Node: Migrate balances to a new file, Next: More detailed close examples, Prev: Retain earnings, Up: close examples + +31.1.9.2 Migrate balances to a new file +....................................... + +Close assets/liabilities on 2022-12-31 and re-open them on 2023-01-01: + +$ hledger close --clopen -f 2022.journal -p 2022 +# copy/paste the closing transaction to the end of 2022.journal +# copy/paste the opening transaction to the start of 2023.journal + + After this, to see 2022's end-of-year balances you must exclude the +closing balances transaction: + +$ hledger -f 2022.journal bs not:desc:'closing balances' + + For more flexibility, it helps to tag closing and opening +transactions with eg 'clopen:NEWYEAR', then you can ensure correct +balances by excluding all opening/closing transactions except the first, +like so: + +$ hledger bs -Y -f 2021.j -f 2022.j -f 2023.j expr:'tag:clopen=2021 or not tag:clopen' +$ hledger bs -Y -f 2021.j -f 2022.j expr:'tag:clopen=2021 or not tag:clopen' +$ hledger bs -Y -f 2022.j -f 2023.j expr:'tag:clopen=2022 or not tag:clopen' +$ hledger bs -Y -f 2021.j expr:'tag:clopen=2021 or not tag:clopen' +$ hledger bs -Y -f 2022.j expr:'tag:clopen=2022 or not tag:clopen' +$ hledger bs -Y -f 2023.j # unclosed file, no query needed + + +File: hledger.info, Node: More detailed close examples, Prev: Migrate balances to a new file, Up: close examples + +31.1.9.3 More detailed close examples +..................................... + +See examples/multi-year. + + +File: hledger.info, Node: rewrite, Prev: close, Up: Data generation commands + +31.2 rewrite +============ + +Print all transactions, rewriting the postings of matched transactions. +For now the only rewrite available is adding new postings, like print +-auto. + +Flags: + --add-posting='ACCT AMTEXPR' add a posting to ACCT, which may be + parenthesised. AMTEXPR is either a literal + amount, or *N which means the transaction's + first matched amount multiplied by N (a + decimal number). Two spaces separate ACCT + and AMTEXPR. + --diff generate diff suitable as an input for + patch tool + + This is a start at a generic rewriter of transaction entries. It +reads the default journal and prints the transactions, like print, but +adds one or more specified postings to any transactions matching QUERY. +The posting amounts can be fixed, or a multiplier of the existing +transaction's first posting amount. + + Examples: + +$ hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100' +$ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"' +$ hledger-rewrite.hs -f rewrites.hledger + + rewrites.hledger may consist of entries like: + += ^income amt:<0 date:2017 + (liabilities:tax) *0.33 ; tax on income + (reserve:grocery) *0.25 ; reserve 25% for grocery + (reserve:) *0.25 ; reserve 25% for grocery + + Note the single quotes to protect the dollar sign from bash, and the +two spaces between account and amount. + + More: + +$ hledger rewrite [QUERY] --add-posting "ACCT AMTEXPR" ... +$ hledger rewrite ^income --add-posting '(liabilities:tax) *.33' +$ hledger rewrite expenses:gifts --add-posting '(budget:gifts) *-1"' +$ hledger rewrite ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' + + Argument for '--add-posting' option is a usual posting of transaction +with an exception for amount specification. More precisely, you can use +''*'' (star symbol) before the amount to indicate that that this is a +factor for an amount of original matched posting. If the amount +includes a commodity name, the new posting amount will be in the new +commodity; otherwise, it will be in the matched posting amount's +commodity. + +* Menu: + +* Re-write rules in a file:: +* Diff output format:: +* rewrite vs print --auto:: + + +File: hledger.info, Node: Re-write rules in a file, Next: Diff output format, Up: rewrite + +31.2.1 Re-write rules in a file +------------------------------- + +During the run this tool will execute so called "Automated Transactions" +found in any journal it process. I.e instead of specifying this +operations in command line you can put them in a journal file. + +$ rewrite-rules.journal + + Make contents look like this: + += ^income + (liabilities:tax) *.33 + += expenses:gifts + budget:gifts *-1 + assets:budget *1 + + Note that ''='' (equality symbol) that is used instead of date in +transactions you usually write. It indicates the query by which you +want to match the posting to add new ones. + +$ hledger rewrite -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal + + This is something similar to the commands pipeline: + +$ hledger rewrite -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \ + | hledger rewrite -f - expenses:gifts --add-posting 'budget:gifts *-1' \ + --add-posting 'assets:budget *1' \ + > rewritten-tidy-output.journal + + It is important to understand that relative order of such entries in +journal is important. You can re-use result of previously added +postings. + + +File: hledger.info, Node: Diff output format, Next: rewrite vs print --auto, Prev: Re-write rules in a file, Up: rewrite + +31.2.2 Diff output format +------------------------- + +To use this tool for batch modification of your journal files you may +find useful output in form of unified diff. + +$ hledger rewrite --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' + + Output might look like: + +--- /tmp/examples/sample.journal ++++ /tmp/examples/sample.journal +@@ -18,3 +18,4 @@ + 2008/01/01 income +- assets:bank:checking $1 ++ assets:bank:checking $1 + income:salary ++ (liabilities:tax) 0 +@@ -22,3 +23,4 @@ + 2008/06/01 gift +- assets:bank:checking $1 ++ assets:bank:checking $1 + income:gifts ++ (liabilities:tax) 0 + + If you'll pass this through 'patch' tool you'll get transactions +containing the posting that matches your query be updated. Note that +multiple files might be update according to list of input files +specified via '--file' options and 'include' directives inside of these +files. + + Be careful. Whole transaction being re-formatted in a style of +output from 'hledger print'. + + See also: + + https://github.com/simonmichael/hledger/issues/99 + + +File: hledger.info, Node: rewrite vs print --auto, Prev: Diff output format, Up: rewrite + +31.2.3 rewrite vs. print -auto +------------------------------ + +This command predates print -auto, and currently does much the same +thing, but with these differences: + + * with multiple files, rewrite lets rules in any file affect all + other files. print -auto uses standard directive scoping; rules + affect only child files. + + * rewrite's query limits which transactions can be rewritten; all are + printed. print -auto's query limits which transactions are + printed. + + * rewrite applies rules specified on command line or in the journal. + print -auto applies rules specified in the journal. + + +File: hledger.info, Node: Maintenance commands, Next: PART 5 COMMON TASKS, Prev: Data generation commands, Up: Top + +32 Maintenance commands +*********************** + +* Menu: + +* check:: +* diff:: +* setup:: +* test:: + + +File: hledger.info, Node: check, Next: diff, Up: Maintenance commands + +32.1 check +========== + +Check for various kinds of errors in your data. + +Flags: +no command-specific flags + + hledger provides a number of built-in correctness checks to help +validate your data and prevent errors. Some are run automatically, some +when you enable '--strict' mode; or you can run any of them on demand by +providing them as arguments to the 'check' command. 'check' produces no +output and a zero exit code if all is well. Eg: + +hledger check # run basic checks +hledger check -s # run basic and strict checks +hledger check ordereddates payees # run basic checks and two others + + If you are an Emacs user, you can also configure flycheck-hledger to +run these checks, providing instant feedback as you edit the journal. + + Here are the checks currently available. They are generally checked +in the order they are shown here, and only the first failure will be +reported. + +* Menu: + +* Basic checks:: +* Strict checks:: +* Other checks:: +* Custom checks:: + + +File: hledger.info, Node: Basic checks, Next: Strict checks, Up: check + +32.1.1 Basic checks +------------------- + +These important checks are performed by default, by almost all hledger +commands: + + * *parseable* - data files are in a supported format, with no syntax + errors and no invalid include directives. This ensures that all + files exist and are readable. + + * *autobalanced* - all transactions are balanced, after automatically + inferring missing amounts and conversion rates and then converting + amounts to cost. This ensures that each transaction's journal + entry is well formed. + + * *assertions* - all balance assertions in the journal are passing. + Balance assertions are a strong defense against errors, catching + many problems. This check is on by default, but if it gets in your + way, you can disable it temporarily with + '-I'/'--ignore-assertions', or as a default by adding that flag to + your config file. (Then use '-s'/'--strict' or 'hledger check + assertions' when you want to enable it). + + +File: hledger.info, Node: Strict checks, Next: Other checks, Prev: Basic checks, Up: check + +32.1.2 Strict checks +-------------------- + +When the '-s'/'--strict' flag is used (AKA strict mode), all commands +will perform the following additional checks (and 'assertions', above). +These provide extra error-catching power to help you keep your data +clean and correct: + + * *balanced* - like 'autobalanced', but implicit conversions between + commodities are not allowed; all conversion transactions must use + cost notation or equity postings. This prevents wrong conversions + caused by typos. + + * *commodities* - all commodity symbols used must be declared. This + guards against mistyping or omitting commodity symbols. + + * *accounts* - all account names used must be declared. This + prevents the use of mis-spelled or outdated account names. + + +File: hledger.info, Node: Other checks, Next: Custom checks, Prev: Strict checks, Up: check + +32.1.3 Other checks +------------------- + +These are not wanted by everyone, but can be run using the 'check' +command: + + * *tags* - all tags used must be declared. This prevents mis-spelled + tag names. Note hledger fairly often finds unintended tags in + comments. + + * *payees* - all payees used in transactions must be declared. This + will force you to declare any new payee name before using it. Most + people will probably find this a bit too strict. + + * *ordereddates* - within each file, transactions must be ordered by + date. This is a simple and effective error catcher. It's not + included in strict mode, but you can add it by running 'hledger + check -s ordereddates'. If enabled, this check is performed before + balance assertions. + + * *recentassertions* - all accounts with balance assertions must have + one that's within the 7 days before their latest posting. This + will encourage adding balance assertions for your active + asset/liability accounts, which in turn should encourage you to + reconcile regularly with those real world balances - another strong + defense against errors. ('hledger close --assert >>$LEDGER_FILE' + is a convenient way to add new balance assertions. Later these + become quite redundant, and you might choose to remove them to + reduce clutter.) + + * *uniqueleafnames* - no two accounts may have the same last account + name part (eg the 'checking' in 'assets:bank:checking'). This + ensures each account can be matched by a unique short name, easier + to remember and to type. + + +File: hledger.info, Node: Custom checks, Prev: Other checks, Up: check + +32.1.4 Custom checks +-------------------- + +You can build your own custom checks with add-on command scripts. See +also Cookbook > Scripting. Here are some examples from hledger/bin/: + + * *hledger-check-tagfiles* - all tag values containing '/' exist as + file paths + + * *hledger-check-fancyassertions* - more complex balance assertions + are passing + + +File: hledger.info, Node: diff, Next: setup, Prev: check, Up: Maintenance commands + +32.2 diff +========= + +Compares a particular account's transactions in two input files. It +shows any transactions to this account which are in one file but not in +the other. + +Flags: +no command-specific flags + + More precisely: for each posting affecting this account in either +file, this command looks for a corresponding posting in the other file +which posts the same amount to the same account (ignoring date, +description, etc). + + Since it compares postings, not transactions, this also works when +multiple bank transactions have been combined into a single journal +entry. + + This command is useful eg if you have downloaded an account's +transactions from your bank (eg as CSV data): when hledger and your bank +disagree about the account balance, you can compare the bank data with +your journal to find out the cause. + + Examples: + +$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro +These transactions are in the first file only: + +2014/01/01 Opening Balances + assets:bank:giro EUR ... + ... + equity:opening balances EUR -... + +These transactions are in the second file only: + + +File: hledger.info, Node: setup, Next: test, Prev: diff, Up: Maintenance commands + +32.3 setup +========== + +Check the status of the hledger installation. + +Flags: +no command-specific flags + + 'setup' tests your hledger installation and prints a list of results, +sometimes with helpful hints. This is a good first command to run after +installing hledger. Also after upgrading, or when something's not +working, or just when you want a reminder of where things are. + + It makes one network request to detect the latest hledger release +version. It's ok if this fails or times out. It will use ANSI color by +default, unless disabled by NO_COLOR or -color=n. It does not use a +pager or a config file. + + It expects that the hledger version you are running is installed in +your PATH. If not, it will stop until you have done that (to keep things +simple). + + Example: + +$ hledger setup +Checking your hledger setup.. +Legend: good, neutral, unknown, warning + +hledger +* is a released version ? no hledger 1.42.99-gbca4b39c5-20250425, mac-aarch64 +* is up to date ? yes 1.42.99 installed, latest is 1.42.1 +* is a native binary for this machine ? yes aarch64 +* is installed in PATH ? yes /Users/simon/.local/bin/hledger +* has a system text encoding configured ? yes UTF-8, data files should use this encoding +* has a user config file ? (optional) no +* current directory has a local config ? yes /Users/simon/src/hledger/hledger.conf +* the config file is readable ? yes /Users/simon/src/hledger/hledger.conf + +terminal +* the NO_COLOR variable is defined ? no +* --color is configured by config file ? no +* hledger will use color by default ? yes +* the PAGER variable is defined ? yes less +* --pager is configured by config file ? no +* hledger will use a pager when needed ? yes /opt/homebrew/bin/less +* the LESS variable is defined ? yes +* the HLEDGER_LESS variable is defined ? no +* adjusting LESS variable for color etc. ? yes +* --pretty is enabled by config file ? no tables will use ASCII characters +* bash shell completions are installed ? ? +* zsh shell completions are installed ? ? + +journal +* the LEDGER_FILE variable is defined ? yes /Users/simon/finance/2025/2025.journal +* a default journal file is readable ? yes /Users/simon/finance/2025/2025.journal +* it includes additional files ? yes 15 +* all commodities are declared ? yes 10 +* all accounts are declared ? yes 160 +* all accounts have types ? no 14 untyped +* accounts of each type were detected ? yes ALERXCV +* commodities/accounts are checked ? no use -s to check commodities/accounts +* balance assertions are checked ? yes use -I to ignore assertions + + +File: hledger.info, Node: test, Prev: setup, Up: Maintenance commands + +32.4 test +========= + +Run built-in unit tests. + +Flags: +no command-specific flags + + This command runs the unit tests built in to hledger and hledger-lib, +printing the results on stdout. If any test fails, the exit code will +be non-zero. + + This is mainly used by hledger developers, but you can also use it to +sanity-check the installed hledger executable on your platform. All +tests are expected to pass - if you ever see a failure, please report as +a bug! + + Any arguments before a '--' argument will be passed to the 'tasty' +test runner as test-selecting -p patterns, and any arguments after '--' +will be passed to tasty unchanged. + + Examples: + +$ hledger test # run all unit tests +$ hledger test balance # run tests with "balance" in their name +$ hledger test -- -h # show tasty's options + + +File: hledger.info, Node: PART 5 COMMON TASKS, Next: Getting help, Prev: Maintenance commands, Up: Top + +33 PART 5: COMMON TASKS +*********************** + +Here are some quick examples of how to do some basic tasks with hledger. + + +File: hledger.info, Node: Getting help, Next: Constructing command lines, Prev: PART 5 COMMON TASKS, Up: Top + +34 Getting help +*************** + +Here's how to list commands and view options and command docs: + +$ hledger # show available commands +$ hledger --help # show common options +$ hledger CMD --help # show CMD's options, common options and CMD's documentation + + You can also view your hledger version's manual in several formats by +using the help command. Eg: + +$ hledger help # show the hledger manual with info, man or $PAGER (best available) +$ hledger help journal # show the journal topic in the hledger manual +$ hledger help --help # find out more about the help command + + To view manuals and introductory docs on the web, visit +https://hledger.org. Chat and mail list support and discussion archives +can be found at https://hledger.org/support. + + +File: hledger.info, Node: Constructing command lines, Next: Starting a journal file, Prev: Getting help, Up: Top + +35 Constructing command lines +***************************** + +hledger has a flexible command line interface. We strive to keep it +simple and ergonomic, but if you run into one of the sharp edges +described in OPTIONS, here are some tips that might help: + + * command-specific options must go after the command (it's fine to + put common options there too: 'hledger CMD OPTS ARGS') + * you can run addon commands via hledger ('hledger ui [ARGS]') or + directly ('hledger-ui [ARGS]') + * enclose "problematic" arguments in single quotes + * if needed, also add a backslash to hide regular expression + metacharacters from the shell + * to see how a misbehaving command line is being parsed, add + '--debug=2'. + + +File: hledger.info, Node: Starting a journal file, Next: Setting LEDGER_FILE, Prev: Constructing command lines, Up: Top + +36 Starting a journal file +************************** + +hledger looks for your accounting data in a journal file, +'$HOME/.hledger.journal' by default: + +$ hledger stats +The hledger journal file "/Users/simon/.hledger.journal" was not found. +Please create it first, eg with "hledger add" or a text editor. +Or, specify an existing journal file with -f or LEDGER_FILE. + + You can override this by setting the 'LEDGER_FILE' environment +variable (see below). It's a good practice to keep this important file +under version control, and to start a new file each year. So you could +do something like this: + +$ mkdir ~/finance +$ cd ~/finance +$ git init +Initialized empty Git repository in /Users/simon/finance/.git/ +$ touch 2023.journal +$ echo "export LEDGER_FILE=$HOME/finance/2023.journal" >> ~/.profile +$ source ~/.profile +$ hledger stats +Main file : /Users/simon/finance/2023.journal +Included files : +Transactions span : to (0 days) +Last transaction : none +Transactions : 0 (0.0 per day) +Transactions last 30 days: 0 (0.0 per day) +Transactions last 7 days : 0 (0.0 per day) +Payees/descriptions : 0 +Accounts : 0 (depth 0) +Commodities : 0 () +Market prices : 0 () + + +File: hledger.info, Node: Setting LEDGER_FILE, Next: Setting opening balances, Prev: Starting a journal file, Up: Top + +37 Setting LEDGER_FILE +********************** + +How to set 'LEDGER_FILE' permanently depends on your setup: + + On unix and mac, running these commands in the terminal will work for +many people; adapt as needed: + +$ echo 'export LEDGER_FILE=~/finance/2023.journal' >> ~/.profile +$ source ~/.profile + + When correctly configured, in a new terminal window 'env | grep +LEDGER_FILE' will show your file, and so will 'hledger files'. + + On mac, this additional step might be helpful for GUI applications +(like Emacs started from the dock): add an entry to +'~/.MacOSX/environment.plist' like + +{ + "LEDGER_FILE" : "~/finance/2023.journal" +} + + and then run 'killall Dock' in a terminal window (or restart the +machine). + + On Windows, see https://www.java.com/en/download/help/path.html, or +try running these commands in a powershell window (let us know if it +persists across a reboot, and if you need to be an Administrator): + +> CD +> MKDIR finance +> SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal" + + When correctly configured, in a new terminal window +'$env:LEDGER_FILE' will show the file path, and so will 'hledger files'. + + +File: hledger.info, Node: Setting opening balances, Next: Recording transactions, Prev: Setting LEDGER_FILE, Up: Top + +38 Setting opening balances +*************************** + +Pick a starting date for which you can look up the balances of some +real-world assets (bank accounts, wallet..) and liabilities (credit +cards..). + + To avoid a lot of data entry, you may want to start with just one or +two accounts, like your checking account or cash wallet; and pick a +recent starting date, like today or the start of the week. You can +always come back later and add more accounts and older transactions, eg +going back to january 1st. + + Add an opening balances transaction to the journal, declaring the +balances on this date. Here are two ways to do it: + + * The first way: open the journal in any text editor and save an + entry like this: + + 2023-01-01 * opening balances + assets:bank:checking $1000 = $1000 + assets:bank:savings $2000 = $2000 + assets:cash $100 = $100 + liabilities:creditcard $-50 = $-50 + equity:opening/closing balances + + These are start-of-day balances, ie whatever was in the account at + the end of the previous day. + + The * after the date is an optional status flag. Here it means + "cleared & confirmed". + + The currency symbols are optional, but usually a good idea as + you'll be dealing with multiple currencies sooner or later. + + The = amounts are optional balance assertions, providing extra + error checking. + + * The second way: run 'hledger add' and follow the prompts to record + a similar transaction: + + $ hledger add + Adding transactions to journal file /Users/simon/finance/2023.journal + Any command line arguments will be used as defaults. + Use tab key to complete, readline keys to edit, enter to accept defaults. + An optional (CODE) may follow transaction dates. + An optional ; COMMENT may follow descriptions or amounts. + If you make a mistake, enter < at any prompt to go one step backward. + To end a transaction, enter . when prompted. + To quit, enter . at a date prompt or press control-d or control-c. + Date [2023-02-07]: 2023-01-01 + Description: * opening balances + Account 1: assets:bank:checking + Amount 1: $1000 + Account 2: assets:bank:savings + Amount 2 [$-1000]: $2000 + Account 3: assets:cash + Amount 3 [$-3000]: $100 + Account 4: liabilities:creditcard + Amount 4 [$-3100]: $-50 + Account 5: equity:opening/closing balances + Amount 5 [$-3050]: + Account 6 (or . or enter to finish this transaction): . + 2023-01-01 * opening balances + assets:bank:checking $1000 + assets:bank:savings $2000 + assets:cash $100 + liabilities:creditcard $-50 + equity:opening/closing balances $-3050 + + Save this transaction to the journal ? [y]: + Saved. + Starting the next transaction (. or ctrl-D/ctrl-C to quit) + Date [2023-01-01]: . + + If you're using version control, this could be a good time to commit +the journal. Eg: + +$ git commit -m 'initial balances' 2023.journal + + +File: hledger.info, Node: Recording transactions, Next: Reconciling, Prev: Setting opening balances, Up: Top + +39 Recording transactions +************************* + +As you spend or receive money, you can record these transactions using +one of the methods above (text editor, hledger add) or by using the +hledger-iadd or hledger-web add-ons, or by using the import command to +convert CSV data downloaded from your bank. + + Here are some simple transactions, see the hledger_journal(5) manual +and hledger.org for more ideas: + +2023/1/10 * gift received + assets:cash $20 + income:gifts + +2023.1.12 * farmers market + expenses:food $13 + assets:cash + +2023-01-15 paycheck + income:salary + assets:bank:checking $1000 + + +File: hledger.info, Node: Reconciling, Next: Reporting, Prev: Recording transactions, Up: Top + +40 Reconciling +************** + +Periodically you should reconcile - compare your hledger-reported +balances against external sources of truth, like bank statements or your +bank's website - to be sure that your ledger accurately represents the +real-world balances (and, that the real-world institutions have not made +a mistake!). This gets easy and fast with (1) practice and (2) +frequency. If you do it daily, it can take 2-10 minutes. If you let it +pile up, expect it to take longer as you hunt down errors and +discrepancies. + + A typical workflow: + + 1. Reconcile cash. Count what's in your wallet. Compare with what + hledger reports ('hledger bal cash'). If they are different, try + to remember the missing transaction, or look for the error in the + already-recorded transactions. A register report can be helpful + ('hledger reg cash'). If you can't find the error, add an + adjustment transaction. Eg if you have $105 after the above, and + can't explain the missing $2, it could be: + + 2023-01-16 * adjust cash + assets:cash $-2 = $105 + expenses:misc + + 2. Reconcile checking. Log in to your bank's website. Compare + today's (cleared) balance with hledger's cleared balance ('hledger + bal checking -C'). If they are different, track down the error or + record the missing transaction(s) or add an adjustment transaction, + similar to the above. Unlike the cash case, you can usually + compare the transaction history and running balance from your bank + with the one reported by 'hledger reg checking -C'. This will be + easier if you generally record transaction dates quite similar to + your bank's clearing dates. + + 3. Repeat for other asset/liability accounts. + + Tip: instead of the register command, use hledger-ui to see a +live-updating register while you edit the journal: 'hledger-ui --watch +--register checking -C' + + After reconciling, it could be a good time to mark the reconciled +transactions' status as "cleared and confirmed", if you want to track +that, by adding the '*' marker. Eg in the paycheck transaction above, +insert '*' between '2023-01-15' and 'paycheck' + + If you're using version control, this can be another good time to +commit: + +$ git commit -m 'txns' 2023.journal + + +File: hledger.info, Node: Reporting, Next: Migrating to a new file, Prev: Reconciling, Up: Top + +41 Reporting +************ + +Here are some basic reports. + + Show all transactions: + +$ hledger print +2023-01-01 * opening balances + assets:bank:checking $1000 + assets:bank:savings $2000 + assets:cash $100 + liabilities:creditcard $-50 + equity:opening/closing balances $-3050 + +2023-01-10 * gift received + assets:cash $20 + income:gifts + +2023-01-12 * farmers market + expenses:food $13 + assets:cash + +2023-01-15 * paycheck + income:salary + assets:bank:checking $1000 + +2023-01-16 * adjust cash + assets:cash $-2 = $105 + expenses:misc + + Show account names, and their hierarchy: + +$ hledger accounts --tree +assets + bank + checking + savings + cash +equity + opening/closing balances +expenses + food + misc +income + gifts + salary +liabilities + creditcard + + Show all account totals: + +$ hledger balance + $4105 assets + $4000 bank + $2000 checking + $2000 savings + $105 cash + $-3050 equity:opening/closing balances + $15 expenses + $13 food + $2 misc + $-1020 income + $-20 gifts + $-1000 salary + $-50 liabilities:creditcard +-------------------- + 0 + + Show only asset and liability balances, as a flat list, limited to +depth 2: + +$ hledger bal assets liabilities -2 + $4000 assets:bank + $105 assets:cash + $-50 liabilities:creditcard +-------------------- + $4055 + + Show the same thing without negative numbers, formatted as a simple +balance sheet: + +$ hledger bs -2 +Balance Sheet 2023-01-16 + + || 2023-01-16 +========================++============ + Assets || +------------------------++------------ + assets:bank || $4000 + assets:cash || $105 +------------------------++------------ + || $4105 +========================++============ + Liabilities || +------------------------++------------ + liabilities:creditcard || $50 +------------------------++------------ + || $50 +========================++============ + Net: || $4055 + + The final total is your "net worth" on the end date. (Or use 'bse' +for a full balance sheet with equity.) + + Show income and expense totals, formatted as an income statement: + +hledger is +Income Statement 2023-01-01-2023-01-16 + + || 2023-01-01-2023-01-16 +===============++======================= + Revenues || +---------------++----------------------- + income:gifts || $20 + income:salary || $1000 +---------------++----------------------- + || $1020 +===============++======================= + Expenses || +---------------++----------------------- + expenses:food || $13 + expenses:misc || $2 +---------------++----------------------- + || $15 +===============++======================= + Net: || $1005 + + The final total is your net income during this period. + + Show transactions affecting your wallet, with running total: + +$ hledger register cash +2023-01-01 opening balances assets:cash $100 $100 +2023-01-10 gift received assets:cash $20 $120 +2023-01-12 farmers market assets:cash $-13 $107 +2023-01-16 adjust cash assets:cash $-2 $105 + + Show weekly posting counts as a bar chart: + +$ hledger activity -W +2019-12-30 ***** +2023-01-06 **** +2023-01-13 **** + + +File: hledger.info, Node: Migrating to a new file, Next: BUGS, Prev: Reporting, Up: Top + +42 Migrating to a new file +************************** + +At the end of the year, you may want to continue your journal in a new +file, so that old transactions don't slow down or clutter your reports, +and to help ensure the integrity of your accounting history. See the +close command. + + If using version control, don't forget to 'git add' the new file. + + +File: hledger.info, Node: BUGS, Prev: Migrating to a new file, Up: Top + +43 BUGS +******* + +We welcome bug reports in the hledger issue tracker +(https://bugs.hledger.org), or on the hledger chat or mail list +(https://hledger.org/support). + + Some known issues and limitations: + + hledger uses the system's text encoding when reading non-ascii text. +If no system encoding is configured, or if the data's encoding is +different, hledger will give an error. (See Text encoding, +Troubleshooting.) + + On Microsoft Windows, depending what kind of terminal window you use, +non-ascii characters, ANSI text formatting, and/or the add command's TAB +key, may not be fully supported. (For best results, try a powershell +window.) + + When processing large data files, hledger uses more memory than +Ledger. + +* Menu: + +* Troubleshooting:: + + +File: hledger.info, Node: Troubleshooting, Up: BUGS + +43.1 Troubleshooting +==================== + +Here are some common issues you might encounter when you run hledger, +and how to resolve them (and remember also you can usually get quick +Support): + + *PATH issues: I get an error like "No command 'hledger' found"* +Depending how you installed hledger, the executables may not be in your +shell's PATH. Eg on unix systems, stack installs hledger in +'~/.local/bin' and cabal installs it in '~/.cabal/bin'. You may need to +add one of these directories to your shell's PATH, and/or open a new +terminal window. + + *LEDGER_FILE issues: I configured LEDGER_FILE but hledger is not +using it* + + * 'LEDGER_FILE' should be a real environment variable, not just a + shell variable. Eg on unix, the command 'env | grep LEDGER_FILE' + should show it. You may need to use 'export' (see + https://stackoverflow.com/a/7411509). On Windows, + '$env:LEDGER_FILE' should show it. + * You may need to force your shell to see the new configuration. A + simple way is to close your terminal window and open a new one. + + *Text decoding issues: I get errors like "Illegal byte sequence" or +"Invalid or incomplete multibyte or wide character" or +"commitAndReleaseBuffer: invalid argument (invalid character)"* +hledger usually needs its input to be decodable with the system locale's +text encoding. See Text encoding and Install: Text encoding. + + *COMPATIBILITY ISSUES: hledger gives an error with my Ledger file* +Not all of Ledger's journal file syntax or feature set is supported. +See hledger and Ledger for full details. + + +Tag Table: +Node: Top208 +Node: PART 1 USER INTERFACE4306 +Node: Input4445 +Node: Text encoding5537 +Node: Data formats6286 +Node: Standard input8020 +Node: Multiple files8409 +Node: Strict mode9146 +Node: Commands9980 +Node: Add-on commands11262 +Node: Options12313 +Node: Special characters19463 +Node: Escaping shell special characters20453 +Node: Escaping regular expression special characters21812 +Node: Escaping in other situations23327 +Node: Unicode characters24475 +Node: Regular expressions25896 +Node: hledger's regular expressions29155 +Node: Argument files30796 +Node: Config files31693 +Node: Shell completions34962 +Node: Output35451 +Node: Output destination35642 +Node: Output format36200 +Node: Text output37986 +Node: Box-drawing characters38970 +Node: Colour39470 +Node: Paging40056 +Node: HTML output41575 +Node: CSV / TSV output41993 +Node: FODS output42247 +Node: Beancount output43051 +Node: Beancount account names44552 +Node: Beancount commodity names45093 +Node: Beancount virtual postings45740 +Node: Beancount metadata46056 +Node: Beancount costs46836 +Node: Beancount operating currency47252 +Node: SQL output47702 +Node: JSON output48493 +Node: Commodity styles49310 +Node: Debug output50197 +Node: Environment51029 +Node: PART 2 DATA FORMATS52198 +Node: Journal52341 +Node: Journal cheatsheet54819 +Node: Comments61070 +Node: Transactions62014 +Node: Dates63151 +Node: Simple dates63303 +Node: Posting dates63919 +Node: Status65006 +Node: Code66772 +Node: Description67107 +Node: Payee and note67794 +Node: Transaction comments68885 +Node: Postings69401 +Node: Debits and credits70564 +Node: The two space delimiter71174 +Node: Account names71739 +Node: Amounts73543 +Node: Decimal marks74572 +Node: Digit group marks75676 +Node: Commodity76311 +Node: Costs77428 +Node: Balance assertions79680 +Node: Assertions and ordering80928 +Node: Assertions and multiple files81647 +Node: Assertions and costs82815 +Node: Assertions and commodities83462 +Node: Assertions and subaccounts85121 +Node: Assertions and status85781 +Node: Assertions and virtual postings86201 +Node: Assertions and auto postings86566 +Node: Assertions and precision87441 +Node: Assertions and hledger add87925 +Node: Posting comments88673 +Node: Transaction balancing89213 +Node: Tags91421 +Node: Querying with tags92715 +Node: Displaying tags93514 +Node: When to use tags ?93910 +Node: Tag names94574 +Node: Special tags95127 +Node: Directives96692 +Node: Directives and multiple files98149 +Node: Directive effects99094 +Node: account directive102250 +Node: Account comments103700 +Node: Account error checking104359 +Node: Account display order105896 +Node: Account types107094 +Node: alias directive110369 +Node: Basic aliases111580 +Node: Regex aliases112455 +Node: Combining aliases113502 +Node: Aliases and multiple files114956 +Node: end aliases directive115739 +Node: Aliases can generate bad account names116107 +Node: Aliases and account types116940 +Node: commodity directive117832 +Node: Commodity directive syntax119419 +Node: Commodity error checking121068 +Node: decimal-mark directive121543 +Node: include directive122122 +Node: P directive124340 +Node: payee directive125374 +Node: tag directive125996 +Node: Periodic transactions126608 +Node: Periodic rule syntax128762 +Node: Periodic rules and relative dates129585 +Node: Two spaces between period expression and description!130362 +Node: Auto postings131323 +Node: Auto postings and multiple files134609 +Node: Auto postings and dates135014 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions135455 +Node: Auto posting tags136301 +Node: Auto postings on forecast transactions only137196 +Node: Other syntax137666 +Node: Balance assignments138438 +Node: Balance assignments and costs139966 +Node: Balance assignments and multiple files140388 +Node: Bracketed posting dates140811 +Node: D directive141509 +Node: apply account directive143282 +Node: Y directive144149 +Node: Secondary dates145137 +Node: Star comments146622 +Node: Valuation expressions147314 +Node: Virtual postings147613 +Node: Other Ledger directives149237 +Node: Other cost/lot notations149999 +Node: CSV152840 +Node: CSV rules cheatsheet155006 +Node: source157304 +Node: Data cleaning / data generating commands158708 +Node: archive160607 +Node: encoding161535 +Node: separator162578 +Node: skip163231 +Node: date-format163881 +Node: timezone164826 +Node: newest-first165952 +Node: intra-day-reversed166665 +Node: decimal-mark167267 +Node: fields list167747 +Node: Field assignment169555 +Node: Field names170774 +Node: date field172106 +Node: date2 field172270 +Node: status field172465 +Node: code field172655 +Node: description field172843 +Node: comment field173060 +Node: account field173617 +Node: amount field174335 +Node: currency field177174 +Node: balance field177582 +Node: if block178105 +Node: Matchers179632 +Node: Multiple matchers181622 +Node: Match groups182430 +Node: if table183323 +Node: balance-type185386 +Node: include186213 +Node: Working with CSV186782 +Node: Rapid feedback187334 +Node: Valid CSV187917 +Node: File Extension188793 +Node: Reading CSV from standard input189528 +Node: Reading multiple CSV files189914 +Node: Reading files specified by rule190390 +Node: Valid transactions191787 +Node: Deduplicating importing192612 +Node: Setting amounts193841 +Node: Amount signs196368 +Node: Setting currency/commodity197433 +Node: Amount decimal places198809 +Node: Referencing other fields200066 +Node: How CSV rules are evaluated201174 +Node: Well factored rules203891 +Node: CSV rules examples204381 +Node: Bank of Ireland204579 +Node: Coinbase206176 +Node: Amazon207359 +Node: Paypal209201 +Node: Timeclock216951 +Node: Timedot221004 +Node: Timedot examples224481 +Node: PART 3 REPORTING CONCEPTS226758 +Node: Time periods226922 +Node: Report start & end date227195 +Node: Smart dates228671 +Node: Report intervals230794 +Node: Date adjustments231368 +Node: Start date adjustment231588 +Node: End date adjustment232491 +Node: Period headings233272 +Node: Period expressions234205 +Node: Period expressions with a report interval236110 +Node: More complex report intervals236558 +Node: Multiple weekday intervals238674 +Node: Depth239685 +Node: Combining depth options240671 +Node: Queries241621 +Node: Query types244293 +Node: acct query244668 +Node: amt query244979 +Node: code query245676 +Node: cur query245871 +Node: desc query246477 +Node: date query246660 +Node: date2 query247056 +Node: depth query247347 +Node: note query247683 +Node: payee query247949 +Node: real query248230 +Node: status query248435 +Node: type query248675 +Node: tag query249208 +Node: Negative queries249837 +Node: not query250019 +Node: Space-separated queries250306 +Node: Boolean queries250994 +Node: expr query252312 +Node: any query252992 +Node: all query253445 +Node: Queries and command options254027 +Node: Queries and account aliases254475 +Node: Queries and valuation254800 +Node: Pivoting255162 +Node: Generating data257438 +Node: Forecasting259238 +Node: --forecast259894 +Node: Inspecting forecast transactions260995 +Node: Forecast reports262328 +Node: Forecast tags263437 +Node: Forecast period in detail264057 +Node: Forecast troubleshooting265145 +Node: Budgeting266216 +Node: Amount formatting266776 +Node: Commodity display style267020 +Node: Rounding268861 +Node: Trailing decimal marks269466 +Node: Amount parseability270399 +Node: Cost reporting272008 +Node: Recording costs272839 +Node: Reporting at cost274566 +Node: Equity conversion postings275331 +Node: Inferring equity conversion postings277976 +Node: Combining costs and equity conversion postings279118 +Node: Requirements for detecting equity conversion postings280343 +Node: Infer cost and equity by default ?281865 +Node: Value reporting282302 +Node: -X Value in specified commodity283260 +Node: -V Value in default commoditys284120 +Node: Valuation date284857 +Node: Finding market price285689 +Node: --infer-market-prices market prices from transactions287069 +Node: Valuation commodity290113 +Node: --value Flexible valuation291546 +Node: Valuation examples293389 +Node: Interaction of valuation and queries295533 +Node: Effect of valuation on reports296250 +Node: PART 4 COMMANDS304100 +Node: Help commands306889 +Node: commands307075 +Node: demo307283 +Node: help308376 +Node: User interface commands310081 +Node: repl310292 +Node: Examples312556 +Node: run313114 +Node: Examples 2315529 +Node: ui316553 +Node: web316690 +Node: Data entry commands316818 +Node: add317079 +Node: add and balance assertions319653 +Node: add and balance assignments320227 +Node: import320922 +Node: Import dry run322001 +Node: Overlap detection322949 +Node: First import325835 +Node: Importing balance assignments327030 +Node: Import and commodity styles328085 +Node: Import archiving328519 +Node: Import special cases329344 +Node: Deduplication329562 +Node: Varying file name330053 +Node: Multiple versions330437 +Node: Basic report commands331544 +Node: accounts331845 +Node: codes334491 +Node: commodities335513 +Node: descriptions336270 +Node: files336730 +Node: notes337027 +Node: payees337539 +Node: prices338451 +Node: stats339343 +Node: tags341084 +Node: Standard report commands342621 +Node: print342926 +Node: print amount explicitness345657 +Node: print alignment346595 +Node: print amount style346909 +Node: print parseability348139 +Node: print other features349416 +Node: print output format350377 +Node: aregister353662 +Node: aregister and posting dates358236 +Node: register359137 +Node: Custom register output366377 +Node: balancesheet367562 +Node: balancesheetequity372527 +Node: cashflow377862 +Node: incomestatement382675 +Node: Advanced report commands387524 +Node: balance387732 +Node: balance features393153 +Node: Simple balance report395256 +Node: Balance report line format397066 +Node: Filtered balance report399426 +Node: List or tree mode399945 +Node: Depth limiting401458 +Node: Dropping top-level accounts402225 +Node: Showing declared accounts402735 +Node: Sorting by amount403465 +Node: Percentages404319 +Node: Multi-period balance report405026 +Node: Balance change end balance407778 +Node: Balance report modes409415 +Node: Calculation mode410094 +Node: Accumulation mode410798 +Node: Valuation mode411899 +Node: Combining balance report modes413243 +Node: Budget report415273 +Node: Using the budget report417573 +Node: Budget date surprises419849 +Node: Selecting budget goals421213 +Node: Budgeting vs forecasting422161 +Node: Balance report layout423838 +Node: Wide layout425043 +Node: Tall layout427448 +Node: Bare layout428754 +Node: Tidy layout430818 +Node: Balance report output432362 +Node: Some useful balance reports433136 +Node: roi434396 +Node: Spaces and special characters in --inv and --pnl436643 +Node: Semantics of --inv and --pnl437369 +Node: IRR and TWR explained439456 +Node: Chart commands442867 +Node: activity443048 +Node: Data generation commands443545 +Node: close443751 +Node: close --clopen446816 +Node: close --close448712 +Node: close --open449236 +Node: close --assert449486 +Node: close --assign449813 +Node: close --retain450492 +Node: close customisation451349 +Node: close and balance assertions453027 +Node: close examples454549 +Node: Retain earnings454786 +Node: Migrate balances to a new file455289 +Node: More detailed close examples456651 +Node: rewrite456873 +Node: Re-write rules in a file459433 +Node: Diff output format460734 +Node: rewrite vs print --auto462004 +Node: Maintenance commands462718 +Node: check462937 +Node: Basic checks464020 +Node: Strict checks465086 +Node: Other checks465959 +Node: Custom checks467661 +Node: diff468100 +Node: setup469308 +Node: test472175 +Node: PART 5 COMMON TASKS473078 +Node: Getting help473311 +Node: Constructing command lines474220 +Node: Starting a journal file475065 +Node: Setting LEDGER_FILE476449 +Node: Setting opening balances477707 +Node: Recording transactions481029 +Node: Reconciling481754 +Node: Reporting484143 +Node: Migrating to a new file488257 +Node: BUGS488706 +Node: Troubleshooting489536  End Tag Table diff --git a/embeddedfiles/hledger.txt b/embeddedfiles/hledger.txt --- a/embeddedfiles/hledger.txt +++ b/embeddedfiles/hledger.txt @@ -16,10665 +16,10721 @@ and largely compatible with ledger(1), and largely interconvertible with beancount(1). - This manual is for hledger's command line interface, version 1.50.2. - It also describes the common options, file formats and concepts used by - all hledger programs. It might accidentally teach you some bookkeep- - ing/accounting as well! You don't need to know everything in here to - use hledger productively, but when you have a question about function- - ality, this doc should answer it. It is detailed, so do skip ahead or - skim when needed. You can read it on hledger.org, or as an info manual - or man page on your system. You can also open a built-in copy, at a - point of interest, by running - hledger --man [CMD], hledger --info [CMD] or hledger help [TOPIC]. - - (And for shorter help, try hledger --tldr [CMD].) - - The main function of the hledger CLI is to read plain text files de- - scribing 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, peo- - ple, etc. You can choose any account names you wish, using : to indi- - cate 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 exten- - sive/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. - -PART 1: USER INTERFACE -Input - hledger reads one or more data files, each time you run it. You can - specify a file with -f, like so - - $ hledger -f FILE [-f FILE2 ...] print - - Files are most often in hledger's journal format, with the .journal - file extension (.hledger or .j also work); these files describe trans- - actions, 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 or- - ganised). So we usually configure a different journal file, by setting - the LEDGER_FILE environment variable, to something like ~/fi- - nance/2023.journal. For more about how to do that on your system, see - Common tasks > Setting LEDGER_FILE. - - Text encoding - hledger expects non-ascii input to be decodable with the system lo- - cale's text encoding. (For CSV/SSV/TSV files, this can be overridden - by the encoding CSV rule.) - - So, trying to read non-ascii files which have the wrong text encoding, - or when no system locale is configured, will fail. To fix this, con- - figure your system locale appropriately, and/or convert the files to - your system's text encoding (using iconv on unix, or powershell or - notepad on Windows). See Install: Text encoding for more tips. - - hledger's output will use the system locale's encoding. - - hledger's docs and example files mostly use UTF-8 encoding. - - Data formats - Usually the data file is in hledger's journal format, but it can be in - any of the supported file formats, which currently are: - - Reader: Reads: Automatically used for - files with extensions: - ----------------------------------------------------------------------------- - journal hledger journal files and some .journal .j .hledger - Ledger journals, for transactions .ledger - timeclock timeclock files, for precise time .timeclock - logging - timedot timedot files, for approximate .timedot - time logging - csv Comma- or other delimiter-sepa- .csv - rated values, for data import - ssv Semicolon separated values .ssv - tsv Tab separated values .tsv - rules CSV/SSV/TSV/other separated val- .rules - ues, alternate way - - These formats are described in more detail below. - - hledger detects the format automatically based on the file extensions - shown above. If it can't recognise the file extension, it assumes - journal format. So for non-journal files, it's important to use a - recognised file extension, so as to either read successfully or to show - relevant error messages. - - You can also force a specific reader/format by prefixing the file path - with the format and a colon. Eg, to read a .dat file containing tab - separated values: - - $ hledger -f tsv:/some/file.dat stats - - Standard input - The file name - means standard input: - - $ cat FILE | hledger -f- print - - If reading non-journal data in this way, you'll need to write the for- - mat as a prefix, like timeclock: here: - - $ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:- - - 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: - - o Balance assertions will not see the effect of transactions in previ- - ous files. (Usually this doesn't matter as each file will set the - corresponding opening balances.) - - o 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. - - Strict mode - hledger checks input files for valid data. By default, the most impor- - tant errors are detected, while still accepting easy journal files - without a lot of declarations: - - o Are the input files parseable, with valid syntax ? - - o Are all transactions balanced ? - - o Do all balance assertions pass ? - - With the -s/--strict flag, additional checks are performed: - - o Are all accounts posted to, declared with an account directive ? - (Account error checking) - - o Are all commodities declared with a commodity directive ? (Commodity - error checking) - - o Are all commodity conversions declared explicitly ? - - You can use the check command to run individual checks - the ones - listed above and some more. - -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 man- - agement. Some often-used commands are add, print, register, bal- - ancesheet and incomestatement. - - To show a summary of commands, run hledger with no arguments. You can - see the same commands summary at the start of PART 4: COMMANDS below. - - To use a particular command, run hledger CMD [CMDOPTS] [CMDARGS], - - o CMD is the full command name, or its standard abbreviation shown in - the commands list, or any unambiguous prefix of the name. - - o CMDOPTS are command-specific options, if any. Command-specific op- - tions must be written after the command name. Eg: hledger print -x. - - o 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 termi- - nal, run hledger CMD -h. Eg: hledger bal -h. - - Add-on commands - In addition to the built-in commands, you can install add-on commands, - which will also appear in hledger's commands list. Some of these can - be installed as separate packages; others can be found in hledger's - bin/ directory, documented at https://hledger.org/scripts.html. - - 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 directly: hledger-ui --watch. - - Or you can run them with hledger, like built-in commands: hledger ui - --watch. In this case hledger's config file will be used, so you can - set custom options for the addon there. (Before hledger 1.50, an -- - argument was needed before addon options, but not any more.) - -Options - Run hledger -h to see general command line help. Options can be writ- - ten either before or after the command name. These options are spe- - cific to the hledger CLI: - - Flags: - --conf=CONFFILE Use extra options defined in this config file. If - not specified, searches upward and in XDG config - dir for hledger.conf (or .hledger.conf in $HOME). - -n --no-conf ignore any config file - - And the following general options are common to most hledger commands: - - General input/data transformation flags: - -f --file=[FMT:]FILE Read data from FILE, or from stdin if FILE is -, - inferring format from extension or a FMT: prefix. - Can be specified more than once. If not specified, - reads from $LEDGER_FILE or $HOME/.hledger.journal. - --rules=RULESFILE Use rules defined in this rules file for - converting subsequent CSV/SSV/TSV files. If not - specified, uses FILE.csv.rules for each FILE.csv. - --alias=A=B|/RGX/=RPL transform account names from A to B, or by - replacing regular expression matches - --auto generate extra postings by applying auto posting - rules ("=") to all transactions - --forecast[=PERIOD] Generate extra transactions from periodic rules - ("~"), from after the latest ordinary transaction - until 6 months from now. Or, during the specified - PERIOD (the equals is required). Auto posting rules - will also be applied to these transactions. In - hledger-ui, also make future-dated transactions - visible at startup. - -I --ignore-assertions don't check balance assertions by default - --txn-balancing=... how to check that transactions are balanced: - 'old': use global display precision - 'exact': use transaction precision (default) - --infer-costs infer conversion equity postings from costs - --infer-equity infer costs from conversion equity postings - --infer-market-prices infer market prices from costs - --pivot=TAGNAME use a different field or tag as account names - -s --strict do extra error checks (and override -I) - --verbose-tags add tags indicating generated/modified data - - General output/reporting flags (supported by some commands): - -b --begin=DATE include postings/transactions on/after this date - -e --end=DATE include postings/transactions before this date - (with a report interval, will be adjusted to - following subperiod end) - -D --daily multiperiod report with 1 day interval - -W --weekly multiperiod report with 1 week interval - -M --monthly multiperiod report with 1 month interval - -Q --quarterly multiperiod report with 1 quarter interval - -Y --yearly multiperiod report with 1 year interval - -p --period=PERIODEXP set begin date, end date, and/or report interval, - with more flexibility - --today=DATE override today's date (affects relative dates) - --date2 match/use secondary dates instead (deprecated) - -U --unmarked include only unmarked postings/transactions - -P --pending include only pending postings/transactions - -C --cleared include only cleared postings/transactions - (-U/-P/-C can be combined) - -R --real include only non-virtual postings - -E --empty Show zero items, which are normally hidden. - In hledger-ui & hledger-web, do the opposite. - --depth=DEPTHEXP if a number (or -NUM): show only top NUM levels - of accounts. If REGEXP=NUM, only apply limiting to - accounts matching the regular expression. - -B --cost show amounts converted to their cost/sale amount - -V --market Show amounts converted to their value at period - end(s) in their default valuation commodity. - Equivalent to --value=end. - -X --exchange=COMM Show amounts converted to their value at period - end(s) in the specified commodity. - Equivalent to --value=end,COMM. - --value=WHEN[,COMM] show amounts converted to their value on the - specified date(s) in their default valuation - commodity or a specified commodity. WHEN can be: - 'then': value on transaction dates - 'end': value at period end(s) - 'now': value today - YYYY-MM-DD: value on given date - -c --commodity-style=S Override a commodity's display style. - Eg: -c '.' or -c '1.000,00 EUR' - --pretty[=YN] Use box-drawing characters in text output? Can be - 'y'/'yes' or 'n'/'no'. - If YN is specified, the equals is required. - - General help flags: - -h --help show command line help - --tldr show command examples with tldr - --info show the manual with info - --man show the manual with man - --version show version information - --debug=[1-9] show this much debug output (default: 1) - --pager=YN use a pager when needed ? y/yes (default) or n/no - --color=YNA --colour use ANSI color ? y/yes, n/no, or auto (default) - - Usually hledger accepts any unambiguous flag prefix, eg you can write - --tl instead of --tldr or --dry instead of --dry-run. - - You can combine short flags which don't take arguments, eg you can - write -MAST instead of -M -A -S -T. Flags requiring an argument can't - be combined in this way (-If FILE won't work). - - If the same option appears more than once in a command line, usually - the last (right-most) wins. Similarly, if mutually exclusive flags are - used together, the right-most wins. (When flags are mutually exclu- - sive, they'll usually have a group prefix in --help.) - - With most commands, arguments are interpreted as a hledger query which - filter the data. Some queries can be expressed either with options or - with arguments. - - Below are more tips for using the command line interface - feel free to - skip these until you need them. - - Special characters - Here we touch on shell escaping/quoting rules, and give some examples. - This is a slightly complicated topic which you may not need at first, - but you should be aware of it, so you can return here when needed. - - If you are able to minimise the use of special characters in your data, - you won't need escaping as much, and your command lines will be sim- - pler. For example, avoiding spaces in account names, and using an - ISO-4217 currency code like USD instead of the $ currency symbol, can - be helpful. - - But if you want to use spaced account names and $, go right ahead; es- - caping isn't a big deal. - - Escaping shell special characters - At the command line, characters which have special meaning for your - shell must be "shell-escaped" (AKA "quoted") if you want hledger to see - them. Often these include space, <, >, (, ), |, \, $ and/or %. - - For example, to match an account name containing the phrase "credit - card", don't write this: - - $ hledger register credit card - - In that command, "credit" and "card" are treated as separate query ar- - guments (described below), so this would match accounts containing ei- - ther word. Instead, enclose the phrase in double or single quotes: - - $ hledger register "credit card" - - In Unix shells, writing a backslash before the character can also work. - Eg: - - $ hledger register credit\ card - - Some shell characters still have a special meaning inside double - quotes, such as the dollar sign ($). Eg in "assets:$account", the bash - shell would replace $account with the value of a shell variable with - that name. When you don't want that, use single quotes, which escape - more strongly: - - $ hledger balance 'assets:$account' - - Escaping on Windows - If you are using hledger in a Powershell or Command window on Microsoft - Windows, the escaping rules are different: - - o In a Powershell window (powershell, blue background), you must use - double quotes or single quotes (not backslash). - - o In a Command window (cmd, black background), you must use double - quotes (not single quotes or backslash). - - The next two sections were written for Unix-like shells, so might need - to be adapted if you're using cmd or powershell. (Edits welcome.) - - Escaping regular expression special characters - Many hledger arguments are regular expressions (described below), and - these too have characters which cause special effects. Some of those - characters are ., ^, $, [, ], (, ), |, and \. When you don't want - these to cause special effects, you can "regex-escape" them by writing - \ (a backslash) before them. But since backslash is also special to - the shell, you may need to also shell-escape the backslashes. - - Eg, in the bash shell, to match a literal $ sign, you could write: - - $ hledger balance cur:\\$ - - or: - - $ hledger balance 'cur:\$' - - (The dollar sign is regex-escaped by the backslash preceding it. Then - that backslash is shell-escaped by another backslash, or by single - quotes.) - - Escaping add-on arguments - When you run an external add-on command with hledger (described below), - any options or arguments being passed through to the add-on executable - lose one level of shell-escaping, so you must add an extra level of - shell-escaping to compensate. - - Eg, in the bash shell, to run the ui add-on and match a literal $ sign, - you need to write: - - $ hledger ui cur:'\\$' - - or: - - $ hledger ui cur:\\\\$ - - If you are wondering why four backslashes: - - o $ is unescaped - - o \$ is regex-escaped - - o \\$ is regex-escaped, then shell-escaped - - o \\\\$ is regex-escaped, then shell-escaped, then both slashes are - shell-escaped once more for hledger argument pass-through. - - Or you can avoid such triple-escaping, by running the add-on executable - directly: - - $ hledger-ui cur:\\$ - - Escaping in other situations - hledger options and arguments are sometimes used in places other than - the command line, with different escaping rules. For example, back- - slash-quoting generally does not work there. Here are some more tips. - - In Windows cmd Use double quotes - In Windows power- Use single or double quotes - shell - In hledger-ui's Use single or double quotes - filter prompt - In hledger-web's Use single or double quotes - search form - In an argument Don't use spaces, don't shell-escape, do regex-es- - file cape when needed - In a config file Use single or double quotes, and enclose the whole - argument ("desc:a b" not desc:"a b") - In ghci (the Use double quotes, and enclose the whole argument - Haskell REPL) - - Using a wild card - When escaping a special character is too much hassle (or impossible), - you can often just write . (period) instead. In regular expressions, - this means "accept any character here". Eg: - - $ hledger register credit.card - - Unicode characters - hledger is expected to handle non-ascii characters correctly: - - o 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.) - - o 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: - - o A system locale must be configured, which can decode the characters - being used. This is essential - see Text encoding and Install: Text - encoding. - - o Your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) - must support unicode. On Windows, you may need to use Windows Termi- - nal. - - o The terminal must be using a font which includes the required unicode - glyphs. - - o The terminal should be configured to display wide characters as dou- - ble width (for report alignment). - - o 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 stan- - dard 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). - - 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-expres- - sions.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 char- - acters 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)$ - - 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 re- - placement string to reference capturing groups in the search regexp. - Otherwise, if you write \1, it will match the digit 1. - - 6. they do not support mode modifiers ((?s)), character classes (\w, - \d), or anything else not mentioned above. - - 7. they may not (I'm guessing not) properly support right-to-left or - bidirectional text. - - Some things to note: - - o In the alias directive and --alias option, regular expressions must - be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, - these are not required. - - o 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:\$. - - o On the command line, some metacharacters like $ have a special mean- - ing to the shell and so must be escaped at least once more. See Spe- - cial characters. - - Argument files - You can save a set of command line options and arguments in a file, and - then reuse them by writing @FILENAME as a command line argument. Eg: - hledger bal @foo.args. - - An argument file's format is more restrictive than the command line. - Each line should contain just one option or argument. Don't use spaces - except inside quotes; write = or nothing between a flag and its argu- - ment. If you use quotes, they must enclose the whole line. For the - special characters mentioned above, use one less level of quoting than - you would at the command line. - - Config files - With hledger 1.40+, you can save extra command line options and argu- - ments in a more featureful hledger config file. Here's a small exam- - ple: - - # General options are listed first, and used with hledger commands that support them. - --pretty - - # Options following a `[COMMAND]` heading are used with that hledger command only. - [print] - --explicit --infer-costs - - To use a config file, specify it with the --conf option. Its options - will be inserted near the start of your command line, so you can over- - ride them with command line options if needed. - - Or, you can set up an automatic config file that is used whenever you - run hledger, by creating hledger.conf in the current directory or - above, or .hledger.conf in your home directory (~/.hledger.conf), or - hledger.conf in your XDG config directory (~/.con- - fig/hledger/hledger.conf). - - Here is another example config you could start with: - https://github.com/simonmichael/hledger/blob/master/hledger.conf.sample - - You can put not only options, but also arguments in a config file. If - the first word in a config file's top (general) section does not begin - with a dash (eg: print), it is treated as the command argument (over- - riding any argument on the command line). - - On unix machines, you can add a shebang line at the top of a config - file, set executable permission on the file, and use it like a script. - Eg (the -S is needed on some operating systems): - - #!/usr/bin/env -S hledger --conf - - You can ignore config files by adding the -n/--no-conf flag to the com- - mand line. This is useful when using hledger in scripts, or when trou- - bleshooting. When both --conf and --no-conf options are used, the - right-most wins. - - To inspect the processing of config files, use --debug or --debug=8. - Or, run the setup command, which will display any active config files. - (setup is not affected by config files itself, unlike other commands.) - - Warning! - - There aren't many hledger features that need a warning, but this is - one! - - Automatic config files, while convenient, also make hledger less pre- - dictable and dependable. It's easy to make a config file that changes - a report's behaviour, or breaks your hledger-using scripts/applica- - tions, in ways that will surprise you later. - - If you don't want this, - - 1. Just don't create a hledger.conf file on your machine. - - 2. Also be alert to downloaded directories which may contain a - hledger.conf file. - - 3. Also if you are sharing scripts or examples or support, consider - that others may have a hledger.conf file. - - Conversely, once you decide to use this feature, try to remember: - - 1. Whenever a hledger command does not work as expected, try it again - with -n (--no-conf) to see if a config file was to blame. - - 2. Whenever you call hledger from a script, consider whether that call - should use -n or not. - - 3. Be conservative about what you put in your config file; try to con- - sider the effect on all your reports. - - 4. To troubleshoot the effect of config files, run with --debug or - --debug 8. - - The config file feature was added in hledger 1.40. - - Shell completions - If you use the bash or zsh shells, you can optionally set up con- - text-sensitive autocompletion for hledger command lines. Try pressing - hledger (should list all hledger commands) or hledger - reg acct: (should list your top-level account names). If - completions aren't working, or for more details, see Install > Shell - completions. - -Output - 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 pro- - vide 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) - - Output format - Some commands offer other kinds of output, not just text on the termi- - nal. Here are those commands and the formats currently supported: - - command txt html csv/tsv fods beancount sql json - -------------------------------------------------------------------------------------------- - aregister Y Y Y Y Y - balance Y Y Y Y Y - balancesheet Y Y Y Y Y - balancesheetequity Y Y Y Y Y - cashflow Y Y Y Y Y - incomestatement Y Y Y Y Y - print Y Y Y Y Y Y Y - register Y Y Y Y Y - - You can also see which output formats a command supports by running - hledger CMD -h and looking for the -O/--output-format=FMT option, - - You can select the output format by using that option: - - $ hledger print -O csv # print CSV to standard output - - or by choosing a suitable filename extension with the -o/--out- - put-file=FILE.FMT option: - - $ hledger balancesheet -o foo.csv # write CSV to foo.csv - - The -O option can be combined with -o to override the file extension if - needed: - - $ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt - - Here are some notes about the various output formats. - - Text output - This is the default: human readable, plain text report output, suitable - for viewing with a monospace font in a terminal. If your data contains - unicode or wide characters, you'll need a terminal and font that render - those correctly. (This can be challenging on MS Windows.) - - Some reports (register, aregister) will normally use the full window - width. If this isn't working or you want to override it, you can use - the -w/--width option. - - Balance reports (balance, balancesheet, incomestatement...) use what- - ever width they need. Multi-period multi-currency reports can often be - wider than the window. Besides using a pager, helpful techniques for - this situation include --layout=bare, -V, cur:, --transpose, --tree, - --depth, --drop, switching to html output, etc. - - Box-drawing characters - hledger draws simple table borders by default, to minimise the risk of - display problems caused by a terminal/font not supporting box-drawing - characters. - - But your terminal and font probably do support them, so we recommend - using the --pretty flag to show prettier tables in the terminal. This - is a good flag to add to your hledger config file. - - Colour - hledger tries to automatically detect ANSI colour and text styling sup- - port and use it when appropriate. (Currently, it is used rather mini- - mally: some reports show negative numbers in red, and help output uses - bold text for emphasis.) - - You can override this by setting the NO_COLOR environment variable to - disable it, or by using the --color/--colour option, perhaps in your - config file, with a y/yes or n/no value to force it on or off. - - Paging - In unix-like environments, when displaying large output (in any output - format) in the terminal, hledger tries to use a pager when appropriate. - (You can disable this with the --pager=no option, perhaps in your con- - fig file.) - - The pager shows one page of text at a time, and lets you scroll around - to see more. While it is active, usually SPACE shows the next page, h - shows help, and q quits. The home/end/page up/page down/cursor keys, - and mouse scrolling, may also work. - - hledger will use the pager specified by the PAGER environment variable, - otherwise less if available, otherwise more if available. (With one - exception: hledger help -p TOPIC will always use less, so that it can - scroll to the topic.) - - The pager is expected to display hledger's ANSI colour and text - styling. If you see junk characters, you might need to configure your - pager to handle ANSI codes. Or you could disable colour as described - above. - - If you are using the less pager, hledger automatically appends a number - of options to the LESS variable to enable ANSI colour and a number of - other conveniences. (At the time of writing: --chop-long-lines - --hilite-unread --ignore-case --no-init --quit-at-eof - --quit-if-one-screen --RAW-CONTROL-CHARS --shift=8 - --squeeze-blank-lines --use-backslash ). If these don't work well, you - can set your preferred options in the HLEDGER_LESS variable, which will - be used instead. - - HTML output - HTML output can be styled by an optional hledger.css file in the same - directory. - - HTML output will be a HTML fragment, not a complete HTML document. - Like other hledger output, for non-ascii characters it will use the - system locale's text encoding (see Text encoding). - - CSV / TSV output - In CSV or TSV output, digit group marks (such as thousands separators) - are disabled automatically. - - FODS output - FODS is the OpenDocument Spreadsheet format as plain XML, as accepted - by LibreOffice and OpenOffice. If you use their spreadsheet applica- - tions, this is better than CSV because it works across locales (decimal - point vs. decimal comma, character encoding stored in XML header, thus - no problems with umlauts), it supports fixed header rows and columns, - cell types (string vs. number vs. date), separation of number and - currency (currency is displayed but the cell type is still a number ac- - cessible for computation), styles (bold), borders. Btw. you can still - extract CSV from FODS/ODS using various utilities like libreoffice - --headless or ods2csv. - - Beancount output - This is Beancount's journal format. You can use this to export your - hledger data to Beancount, eg to use the Fava web app. - - hledger will try to adjust your data to suit Beancount, automatically. - Be cautious and check the conversion until you are confident it is - good. If you plan to export to Beancount often, you may want to follow - its conventions, for a cleaner conversion: - - o use Beancount-friendly account names - - o use currency codes instead of currency symbols - - o use cost notation instead of equity conversion postings - - o avoid virtual postings, balance assignments, and secondary dates. - - There is one big adjustment you must handle yourself: for Beancount, - the top level account names must be Assets, Liabilities, Equity, In- - come, and/or Expenses. You can use account aliases to rewrite your ac- - count names temporarily, if needed, as in this hledger2beancount.conf - config file. - - 2024-12-20: Some more things not yet handled for you: - - o P directives are not converted automatically - convert those your- - self. - - o Balance assignments are not converted (Beancount doesn't support - them) - replace those with explicit amounts. - - Beancount account names - Aside from the top-level names, hledger will adjust your account names - to make valid Beancount account names, by capitalising each part, re- - placing spaces with -, replacing other unsupported characters with - C, prepending A to account name parts which don't begin with - a letter or digit, and appending :A to account names which have only - one part. - - Beancount commodity names - hledger will adjust your commodity names to make valid Beancount com- - modity/currency names, which must be 2-24 uppercase letters, digits, or - ', ., _, -, beginning with a letter and ending with a letter or digit. - hledger will convert known currency symbols to ISO 4217 currency codes, - capitalise letters, replace spaces with -, replace other unsupported - characters with C, and prepend or append C if needed. - - Beancount virtual postings - Beancount doesn't allow virtual postings; if you have any, they will be - omitted from beancount output. - - Beancount metadata - hledger tags will be converted to Beancount metadata (except for tags - whose name begins with _). Metadata names will be adjusted to be Bean- - count-compatible: beginning with a lowercase letter, at least two char- - acters long, and with unsupported characters encoded. Metadata values - will use Beancount's string type. - - In hledger, objects can have the same tag repeated with multiple val- - ues. Eg an assets:cash account might have both type:Asset and - type:Cash tags. For Beancount these will be combined into one, with - the values combined, comma separated. Eg: type: "Asset, Cash". - - Beancount costs - Beancount doesn't allow redundant costs and conversion postings as - hledger does. If you have any of these, the conversion postings will - be omitted. Currently we support at most one cost + conversion post- - ings group per transaction. - - Beancount operating currency - Declaring an operating currency (or several) improves Beancount and - Fava reports. Currently hledger will declare each currency used in - cost amounts as an operating currency. If needed, replace these with - your own declaration, like - - option "operating_currency" "USD" - - SQL output - SQL output is expected to work at least with SQLite, MySQL and Post- - gres. - - The SQL statements are expected to be executed in the empty database. - If you already have tables created via SQL output of hledger, you would - probably want to either clear data from these (via delete or truncate - SQL statements) or drop the tables completely before import; otherwise - your postings would be duplicated. - - For SQLite, it is more useful if you modify the generated id field to - be a PRIMARY KEY. Eg: - - $ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ... - - This is not yet much used; feedback is welcome. - - JSON output - Our JSON is rather large and verbose, since it is a faithful represen- - tation of hledger's internal data types. To understand its structure, - read the Haskell type definitions, which are mostly in - https://github.com/simonmichael/hledger/blob/mas- - ter/hledger-lib/Hledger/Data/Types.hs. hledger-web's OpenAPI specifi- - cation may also be relevant. - - hledger stores numbers with sometimes up to 255 significant digits. - This is too many digits for most JSON consumers, so in JSON output we - round numbers to at most 10 decimal places. (We don't limit the number - of integer digits.) If you find this causing problems, please let us - know. Related: #1195 - - This is not yet much used; feedback is welcome. - - 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 (ex- - cept for cost amounts and amounts displayed by the print command, which - are always displayed with all decimal digits). For example, the fol- - lowing will force dollar amounts to be displayed as shown: - - $ hledger print -c '$1.000,0' - - This option can be repeated to set the display style for multiple com- - modities/currencies. Its argument is as described in the commodity di- - rective. - - In some cases hledger will adjust number formatting to improve their - parseability (such as adding trailing decimal marks when needed). - - 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 re- - veal when parts of the code are evaluated. To capture debug output in - a log file instead, you can usually redirect stderr, eg: - - hledger bal --debug=3 2>hledger.log - - (This option doesn't work in a config file yet.) - -Environment - These environment variables affect hledger: - - HLEDGER_LESS If less is your pager, this variable specifies the less - options hledger should use. (Otherwise, LESS + custom options are - used.) - - LEDGER_FILE The main journal file to use when not specified with - -f/--file. Default: $HOME/.hledger.journal. - - NO_COLOR If this environment variable exists (with any value, including - empty), hledger will not use ANSI color codes in terminal output, un- - less overridden by an explicit --color=y or --colour=y option. - -PART 2: DATA FORMATS -Journal - hledger's usual data source is a plain text file containing journal en- - tries in hledger journal format. If you're looking for a quick refer- - ence, jump ahead to the journal cheatsheet (or use the table of con- - tents at https://hledger.org/hledger.html). - - This file represents an accounting General Journal. The .journal file - extension is most often used, though not strictly required. The jour- - nal file contains a number of transaction entries, each describing a - transfer of money (or any commodity) between two or more named ac- - counts, 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 in- - compatible features, you can keep your hledger journal readable by - Ledger and vice versa. This can useful eg for comparing the behaviour - of one app against the other. - - You can use hledger without learning any more about this file; just use - the add or web or import commands to create and update it. - - Many users, though, edit the journal file with a text editor, and track - changes with a version control system such as git. Editor add-ons such - as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and - hledger-vscode for Visual Studio Code, make this easier, adding colour, - formatting, tab completion, and useful commands. See Editor configura- - tion at hledger.org for the full list. - - A hledger journal file can contain three kinds of thing: comment lines, - transactions, and/or directives (including periodic transaction rules - and auto posting rules). Understanding the journal file format will - also give you a good understanding of hledger's data model. Here's a - quick cheatsheet/overview, followed by detailed descriptions of each - part. - - Journal cheatsheet - # Here is the main syntax of hledger's journal format - # (omitting extra Ledger compatibility syntax). - - ############################################################################### - - # 1. These are comment lines, for notes or temporarily disabling things. - ; They begin with # or ; - - comment - Or, lines can be enclosed within "comment" / "end comment". - This is a block of - commented lines. - end comment - - # Some journal entries can have semicolon comments at end of line ; like this - # Some of them require 2 or more spaces before the semicolon. - - ############################################################################### - - # 2. Directives customise processing or output in some way. - # You don't need any directives to get started. - # But they can add more error checking, or change how things are displayed. - # They begin with a word, letter, or symbol. - # They are most often placed at the top, before transactions. - - account assets ; Declare valid account names and display order. - account assets:savings ; A subaccount. This one represents a bank account. - account assets:checking ; Another. Note, 2+ spaces after the account name. - account assets:receivable ; Accounting type is inferred from english names, - account passifs ; or declared with a "type" tag, type:L - account expenses ; type:X - ; A follow-on comment line, indented. - account expenses:rent ; Expense and revenue categories are also accounts. - ; Subaccounts inherit their parent's type. - - commodity $0.00 ; Declare valid commodities and their display styles. - commodity 1.000,00 EUR - - decimal-mark . ; The decimal mark used in this file (if ambiguous). - - payee Whole Foods ; Declare a valid payee name. - - tag trip ; Declare a valid tag name. - - P 2024-03-01 AAPL $179 ; Declare a market price for AAPL in $ on this date. - - include other.journal ; Include another journal file here. - - # Declare a recurring "periodic transaction", for budget/forecast reports - ~ monthly set budget goals ; <- Note, 2+ spaces before the description. - (expenses:rent) $1000 - (expenses:food) $500 - - # Declare an auto posting rule, to modify existing transactions in reports - = revenues:consulting - liabilities:tax:2024:us *0.25 ; Add a tax liability & expense - expenses:tax:2024:us *-0.25 ; for 25% of the revenue. - - ############################################################################### - - # 3. Transactions are what it's all about. - # They are dated events, usually movements of money between 2 or more accounts. - # They begin with a numeric date. - # Here is their basic shape: - # - # DATE DESCRIPTION ; The transaction's date and optional description. - # ACCOUNT1 AMOUNT ; A posting of an amount to/from this account, indented. - # ACCOUNT2 AMOUNT ; A second posting, balancing the first. - # ... ; More if needed. Amounts must sum to zero. - # ; Note, 2+ spaces between account names and amounts. - - 2024-01-01 opening balances ; At the start, declare pre-existing balances this way. - assets:savings $10000 ; Account names can be anything. lower case is easy to type. - assets:checking $1000 ; assets, liabilities, equity, revenues, expenses are common. - liabilities:credit card $-500 ; liabilities, equity, revenues balances are usually negative. - equity:start ; One amount can be left blank. $-10500 is inferred here. - ; Some of these accounts we didn't declare above, - ; so -s/--strict would complain. - - 2024-01-03 ! (12345) pay rent - ; Additional transaction comment lines, indented. - ; There can be a ! or * after the date meaning "pending" or "cleared". - ; There can be a parenthesised (code) after the date/status. - ; Amounts' sign shows direction of flow. - assets:checking $-500 ; Minus means removed from this account (credit). - expenses:rent $500 ; Plus means added to this account (debit). - - ; Keeping transactions in date order is optional (but helps error checking). - - 2024-01-02 Gringott's Bank | withdrawal ; Description can be PAYEE | NOTE - assets:bank:gold -10 gold - assets:pouch 10 gold - - 2024-01-02 shopping - expenses:clothing 1 gold - expenses:wands 5 gold - assets:pouch -6 gold - - 2024-01-02 receive gift - revenues:gifts -3 "Chocolate Frogs" ; Complex commodity symbols - assets:pouch 3 "Chocolate Frogs" ; must be in double quotes. - - 2024-01-15 buy some shares, in two lots ; Cost can be noted. - assets:investments:2024-01-15 2.0 AAAA @ $1.50 ; @ means per-unit cost - assets:investments:2024-01-15-02 3.0 AAAA @@ $4 ; @@ means total cost - ; ^ Per-lot subaccounts are sometimes useful. - assets:checking $-7 - - 2024-01-15 assert some account balances on this date - ; Balances can be asserted in any transaction, with =, for extra error checking. - ; Assertion txns like this one can be made with hledger close --assert --show-costs - ; - assets:savings $0 = $10000 - assets:checking $0 = $493 - assets:bank:gold 0 gold = -10 gold - assets:pouch 0 gold = 4 gold - assets:pouch 0 "Chocolate Frogs" = 3 "Chocolate Frogs" - assets:investments:2024-01-15 0.0 AAAA = 2.0 AAAA @ $1.50 - assets:investments:2024-01-15-02 0.0 AAAA = 3.0 AAAA @@ $4 - liabilities:credit card $0 = $-500 - - 2024-02-01 note some event, or a transaction not yet fully entered, on this date - ; Postings are not required. - - # Consistent YYYY-MM-DD date format is recommended, - # but you can use . or / and omit leading zeros if you prefer. - 2024.01.01 - 2024/1/1 - - 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 re- - gions beginning with a comment line and ending with an end comment line - (or file end). Here's a suggestion for choosing between them: - - o # for top-level notes - - o ; for commenting out things temporarily - - o 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 com- - ments, and Account comments below. - - 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 sim- - ple date in column 0. This can be followed by any of the following op- - tional fields, separated by spaces: - - o a status character (empty, !, or *) - - o a code (any short number or text, enclosed in parentheses) - - o a description (any remaining text until end of line or a semicolon) - - o a comment (any remaining text following a semicolon until end of - line, and any following indented lines beginning with a semicolon) - - o 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 - - Dates - 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 cur- - rent transaction, the default year set with a Y directive, or the cur- - rent 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.) - - 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 re- - ports, 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. - - Status - Transactions (or individual postings within a transaction) can have a - status mark, which is a single character before the transaction de- - scription (or posting account name), separated from it by a space, in- - dicating one of three statuses: - - mark status - ------------------ - unmarked - ! pending - * cleared - - When reporting, you can filter by status with the -U/--unmarked, - -P/--pending, and -C/--cleared flags (and you can combine these, eg -UP - to match all except cleared things). Or you can use the status:, sta- - tus:!, and status:* queries, or the U, P, C keys in hledger-ui. - - (Note: in Ledger the "unmarked" state is called "uncleared"; in hledger - we renamed it to "unmarked" for semantic clarity.) - - Status marks are optional, but can be helpful eg for reconciling with - real-world accounts. Some editor modes provide highlighting and short- - cuts 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 reconcil- - iation) - cleared complete, reconciled as far as possible, and considered cor- - rect - - 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 un- - cashed checks), and no flags to see the most up-to-date state of your - finances. - - 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. - - Description - After the date, status mark and/or code fields, the rest of the line - (or until a comment is begun with ;) is the transaction's description. - Here you can describe the transaction (called the "narration" in tradi- - tional bookkeeping), or you can record a payee/payer name, or you can - leave it empty. - - Transaction descriptions show up in print output and in register re- - ports, and can be listed with the descriptions command. - - You can query by description with desc:DESCREGEX, or pivot on descrip- - tion with --pivot desc. - - Payee and note - Sometimes people want a dedicated payee/payer field that can be queried - and checked more strictly. If you want that, you can write a | (pipe) - character in the description. This divides it into a "payee" field on - the left, and a "note" field on the right. (Either can be empty.) - - You can query these with payee:PAYEEREGEX and note:NOTEREGEX, list - their values with the payees and notes commands, or pivot on payee or - note. - - Note: in transactions with no | character, description, payee, and note - all have the same value. Once a | is added, they become distinct. (If - you'd like to change this behaviour, please propose it on the mail - list.) - - If you want more strict error checking, you can declare the valid payee - names with payee directives, and then enforce these with hledger check - payees. (Note: because of the above, for this you'll need to ensure - every transaction description contains a | and therefore a checkable - payee name, even if it's empty.) - - 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 - - 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: - - o (optional) a status character (empty, !, or *), followed by a space - - o (required) an account name (any text, optionally containing single - spaces, until end of line or a double space) - - o (optional) two or more spaces (or tabs) followed by an amount. - - If the amount is positive, it is being added to the account; if nega- - tive, it is being removed from the account. - - The posting amounts in a transaction must sum up to zero, indicating - that the inflows and outflows are equal. We call this a balanced - transaction. (You can read more about the nitty-gritty details of "sum - up to zero" in Transaction balancing below.) - - As a convenience, you can optionally leave one amount blank; hledger - will infer what it should be so as to balance the transaction. - - Debits and credits - The traditional accounting concepts of debit and credit of course exist - in hledger, but we represent them with numeric sign, as described - above. Positive and negative posting amounts represent debits and - credits respectively. - - You don't need to remember that, but if you would like to - eg for - helping newcomers or for talking with your accountant - here's a handy - mnemonic: - - debit / plus / left / short words - credit / minus / right / longer words - - The two space delimiter - Be sure to notice the unusual separator between the account name and - the following amount. Because hledger allows account names with spaces - in them, you must separate the account name and amount (if any) by two - or more spaces (or tabs). It's easy to forget at first. If you ever - see the amount being treated as part of the account name, you'll know - you probably need to add another space between them. - - 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, liabil- - ities, 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, num- - bers, 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 vir- - tual 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. - - Amounts - After the account name, there is usually an amount. (Remember: between - account name and amount, there must be two or more spaces.) - - hledger's amount format is flexible, supporting several international - formats. Here are some examples. Amounts have a number (the "quan- - tity"): - - 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 com- - modity 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 - - Decimal marks - A decimal mark can be written as a period or a comma: - - 1.23 - 1,23 - - Both of these are common in international number formats, so hledger is - not biased towards one or the other. Because hledger also supports - digit group marks (eg thousands separators), this means that a number - like 1,000 or 1.000 containing just one period or comma is ambiguous. - In such cases, hledger by default assumes it is a decimal mark, and - will parse both of those as 1. - - To help hledger parse such ambiguous numbers more accurately, if you - use digit group marks, we recommend declaring the decimal mark explic- - itly. The best way is to add a decimal-mark directive at the top of - each data file, like this: - - decimal-mark . - - Or you can declare it per commodity with commodity directives, de- - scribed below. - - hledger also accepts numbers like 10. with no digits after the decimal - mark (and will sometimes display numbers that way to disambiguate them - - see Trailing decimal marks). - - Digit group marks - In the integer part of the amount quantity (left of the decimal mark), - groups of digits can optionally be separated by a digit group mark - a - comma or period (whichever is not used as decimal mark), or a space - (several Unicode space variants, like no-break space, are also ac- - cepted). So these are all valid amounts in a journal file: - - $1,000,000.00 - EUR 2.000.000,00 - INR 9,99,99,999.00 - 1 000 000.00 ; <- ordinary space - 1 000 000.00 ; <- no-break space - - 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 punctu- - ation), you must always write it inside double quotes ("green apples", - "ABC123"). - - If you write just a bare number, that too will have a commodity, with - name ""; we call that the "no-symbol commodity". - - Actually, hledger combines these single-commodity amounts into more - powerful multi-commodity amounts, which are what it works with most of - the time. A multi-commodity amount could be, eg: 1 USD, 2 EUR, 3.456 - TSLA. In practice, you will only see multi-commodity amounts in - hledger's output; you can't write them directly in the journal file. - - By default, the format of amounts in the journal influences how hledger - displays them in output. This is explained in Commodity display style - below. - - Costs - After a posting amount, you can note its cost (when buying) or selling - price (when selling) in another commodity, by writing either @ UNIT- - PRICE or @@ TOTALPRICE after it. This indicates a conversion transac- - tion, 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 in- - ferred 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 im- - plicitly: - - 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. - - 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 pro- - tect 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). - - Assertions and ordering - hledger calculates and checks an account's balance assertions in date - order (and when there are multiple assertions on the same day, in parse - order). Note this is different from Ledger, which checks assertions - always in parse order, ignoring dates. - - This means in hledger you can freely reorder transactions, postings, or - files, and balance assertions will usually keep working. The exception - is when you reorder multiple postings on the same day, to the same ac- - count, which have balance assertions; those will likely need updating. - - Assertions and multiple files - If an account has transactions appearing in multiple files, balance as- - sertions can still work - but only if those files are part of a hierar- - chy made by include directives. - - If the same files are specified with two -f options on the command - line, the assertions in the second will not see the balances from the - first. - - To work around this, arrange your files in a hierarchy with include. - Or, you could concatenate the files temporarily, and process them like - one big file. - - Why does it work this way ? It might be related to hledger's goal of - stable predictable reports. File hierarchy is considered "permanent", - part of your data, while the order of command line options/arguments is - not. We don't want transient changes to be able to change the meaning - of the data. Eg it would be frustrating if tomorrow all your balance - assertions broke because you wrote command line arguments in a differ- - ent order. (Discussion welcome.) - - Assertions and costs - Balance assertions ignore costs, and should normally be written without - one: - - 2019/1/1 - (a) $1 @ 1 = $1 - - We do allow costs to be written in balance assertion amounts, however, - and print shows them, but they don't affect whether the assertion - passes or fails. This is for backward compatibility (hledger's close - command used to generate balance assertions with costs), and because - balance assignments do use costs (see below). - - Assertions and commodities - The balance assertions described so far are "single commodity balance - assertions": they assert and check the balance in one commodity, ignor- - ing any others that may be present. This is how balance assertions - work in Ledger also. - - If an account contains multiple commodities, you can assert their bal- - ances by writing multiple postings with balance assertions, one for - each commodity: - - 2013/1/1 - usd $-1 - eur -1 - both - - 2013/1/2 - both 0 = $1 - both 0 = 1 - - In hledger you can make a stronger "sole commodity balance assertion" - by writing two equals signs (== EXPECTEDBALANCE). This also asserts - that there are no other commodities in the account besides the asserted - one (or at least, that their current balance is zero): - - 2013/1/1 - usd $-1 == $-1 ; these sole commodity assertions succeed - eur -1 == -1 - both ;== $1 ; this one would fail because 'both' contains $ and - - It's less easy to make a "sole commodities balance assertion" (note the - plural) - ie, asserting that an account contains two or more specified - commodities and no others. It can be done by - - 1. isolating each commodity in a subaccount, and asserting those - - 2. and also asserting there are no commodities in the parent account - itself: - - 2013/1/1 - usd $-1 - eur -1 - both 0 == 0 ; nothing up my sleeve - both:usd $1 == $1 ; a dollar here - both:eur 1 == 1 ; a euro there - - Assertions and subaccounts - All of the balance assertions above (both = and ==) are "subaccount-ex- - clusive balance assertions"; they ignore any balances that exist in - deeper subaccounts. - - In hledger you can make "subaccount-inclusive balance assertions" by - adding a star after the equals (=* or ==*): - - 2019/1/1 - equity:start - assets:checking $10 - assets:savings $10 - assets $0 ==* $20 ; assets + subaccounts contains $20 and nothing else - - Assertions and status - Balance assertions always consider postings of all statuses (unmarked, - pending, or cleared); they are not affected by the -U/--unmarked / - -P/--pending / -C/--cleared flags or the status: query. - - 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. - - 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: - - o assert the balance calculated with --auto, and always use --auto with - that file - - o or assert the balance calculated without --auto, and never use --auto - with that file - - o or avoid balance assertions on accounts affected by auto postings (or - avoid auto postings entirely). - - 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 asser- - tions. Balance assertion failure messages show exact amounts. - - Assertions and hledger add - Balance assertions can be included in the amounts given in add. All - types of assertions are supported, and assertions can be used as in a - normal journal file. - - All transactions, not just those that have an explicit assertion, are - validated against the existing assertions in the journal. This means - it is possible for an added transaction to fail even if its assertions - are correct as of the transaction date. - - If this assertion checking is not desired, then it can be disabled with - -I. - - However, balance assignments are currently not supported. - - 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 - - Transaction balancing - How exactly does hledger decide when a transaction is balanced ? Espe- - cially when it involves costs, which often are not exact, because of - repeating decimals, or imperfect data from financial institutions ? In - each commodity, hledger sums the transaction's posting amounts, after - converting any with costs; then it checks if that sum is zero, when - rounded to a suitable number of decimal digits - which we call the bal- - ancing precision. - - Since version 1.50, hledger infers balancing precision in each transac- - tion from the amounts in that transaction's journal entry (like - Ledger). Ie, when checking the balance of commodity A, it uses the - highest decimal precision seen for A in the journal entry (excluding - cost amounts). This makes transaction balancing robust; any imbalances - must be visibly accounted for in the journal entry, display precision - can be freely increased with -c, and compatibility with Ledger and - Beancount journals is good. - - Note that hledger versions before 1.50 worked differently: they allowed - display precision to override the balancing precision. This masked - small imbalances and caused fragility (see issue #2402). As a result, - some journal entries (or CSV rules) that worked with hledger <1.50, are - now rejected with an "unbalanced transaction" error. If you hit this - problem, it's easy to fix: - - o You can restore the old behaviour, by adding --txn-balancing=old to - the command or to your ~/.hledger.conf file. This lets you keep us- - ing old journals unchanged, though without the above benefits. - - o Or you can fix the problem entries (recommended). There are three - ways, use whichever seems best: - - 1. make cost amounts more precise (add more/better decimal digits) - - 2. or make non-cost amounts less precise (remove unnecessary decimal - digits that are raising the precision) - - 3. or add a posting to absorb the imbalance (eg "expenses:rounding". - Remember that one posting may omit the amount; that's convenient - here.) - - Tags - Tags are a way to add extra labels or data fields to transactions, - postings, or accounts. They are usually a word or hyphenated word, im- - mediately followed by a full colon, written within the comment of a - transaction, a posting, or an account directive. (Yes, storing data in - comments is slightly weird!) - - You can write each tag on its own comment line, or multiple tags on one - line, separated by commas. Tags can also have a value, which is any - text after the colon until the next comma or end of line, excluding - surrounding whitespace. (hledger tag values can't contain commas.) If - the same tag name appears multiple times in a comment, each name:value - pair is preserved. - - An example: in this journal there are six tags, one of them with a - value: - - account assets:checking ; accounttag: - account expenses:food - - 2017/1/16 bought groceries ; transactiontag: - ; transactiontag2: - assets:checking $-1 - ; posting-tag-1:, (belongs to the posting above) - expenses:food $1 ; posting-tag-2:, posting-tag-3: with a value - - Querying with tags - Tags are most often used to select a subset of data; you can match - tagged things by tag name and or tag value with a tag: query. (See - queries below.) - - When querying for tag names or values, note that postings inherit tags - from their transaction and from their account, and transactions acquire - tags from their postings. So in the example above, - the assets:check- - ing posting effectively has four tags (one of its own, one from the ac- - count, two from the transaction) - the expenses:food posting effec- - tively has four tags (two of its own, two from the transaction) - the - transaction effectively has all six tags (two of its own, and two from - each posting) - - Displaying tags - You can use the tags command to list tag names or values. - - The print command also shows tags. - - You can use --pivot to display tag values in other reports, in various - ways (eg appended to account names, like pseudo subaccounts). - - When to use tags ? - Tags provide more dimensions of categorisation, complementing accounts - and transaction descriptions. When to use each of these is somewhat a - matter of taste. Accounts have the most built-in support, and regex - queries on descriptions are also quite powerful. So you may not need - tags at all. But if you want to track multiple cross-cutting cate- - gories, they can be a good fit. For example, you could tag trip-re- - lated transactions with trip: YEAR:PLACE, without disturbing your usual - account categories. - - Tag names - What is allowed in a tag name ? Currently, most non-whitespace charac- - ters. Eg : is a valid tag. - - For extra error checking, you can declare valid tag names with the tag - directive, and then enforce these with the check command. - - But note that tags are detected quite loosely at present, sometimes - where you didn't intend them. Eg ; see https://foo.com contains a - https tag with value //foo.com. - - Special tags - Some tag names have special significance to hledger. They are ex- - plained elsewhere, but here's a quick reference: - - type -- declares an account's type - date -- overrides a posting's date - date2 -- overrides a posting's secondary date - assert -- appears on txns generated by close --assert - retain -- appears on txns generated by close --retain - start -- appears on txns generated by close --migrate/--close/--open/--assign - t -- appears on postings generated from timedot letters - - generated-transaction -- appears on txns generated by a periodic rule - modified-transaction -- appears on txns which have had auto postings added - generated-posting -- appears on generated postings - cost-posting -- appears on postings which have (or could have) a cost, - and which have equivalent conversion postings in the transaction - conversion-posting -- appears on postings which are to a V/Conversion account - and which have an equivalent cost posting in the transaction - - The second group above (generated-transaction, etc.) are normally hid- - den, with a _ prefix added. This means print doesn't show them by de- - fault; but you can still use them in queries. You can add the --ver- - bose-tags flag to make them visible, which can be useful for trou- - bleshooting. - - 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 spe- - cific 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 di- - rectives: - - 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 bud- ~ - get goals - Generate extra postings on existing = - transactions - CHECKING FOR ERRORS: - Define valid entities to provide more account, commodity, payee, tag - error checking - REPORTING: - Declare accounts' type and display order account - Declare commodity display styles commodity - Declare market prices P - - Directives and multiple files - Directives vary in their scope, ie which journal entries and which in- - put files they affect. Most often, a directive will affect the follow- - ing 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 di- - rectives in your files. - - Directive effects - Here are all hledger's directives, with their effects and scope sum- - marised - nine main directives, plus four others which we consider - non-essential: - - di- what it does ends - rec- at - tive file - end? - -------------------------------------------------------------------------------------- - ac- Declares an account, for checking all entries in all files; and N - count its display order and type. Subdirectives: any text, ignored. - alias Rewrites account names, in following entries until end of cur- Y - rent file or end aliases. Command line equivalent: --alias - com- Ignores part of the journal file, until end of current file or Y - ment end comment. - com- Declares up to four things: 1. a commodity symbol, for checking N,N,Y,Y - mod- all amounts in all files 2. the display style for all amounts - ity of this commodity 3. the decimal mark for parsing amounts of - this commodity, in the rest of this file and its children, if - there is no decimal-mark directive 4. the precision to use for - balanced-transaction checking in this commodity, in this file - and its children. Takes precedence over D. Subdirectives: - format (ignored). Command line equivalent: -c/--commodity-style - deci- Declares the decimal mark, for parsing amounts of all commodi- Y - mal-mark ties in following entries until next decimal-mark or end of cur- - rent file. Included files can override. Takes precedence over - commodity and D. - include Includes entries and directives from another file, as if they N - 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: - apply Prepends a common parent account to all account names, in fol- Y - account lowing 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). - Other Other directives from Ledger's file format are accepted but ig- - Ledger nored. - direc- - tives - - account directive - account directives can be used to declare accounts (ie, the places that - amounts are transferred from and to). Though not required, these dec- - larations can provide several benefits: - - o They can document your intended chart of accounts, providing a refer- - ence. - - o They can store additional account information as comments, or as tags - which can be used to filter or pivot reports. - - o They can restrict which accounts may be posted to by transactions, eg - in strict mode, which helps prevent errors. - - o They influence account display order in reports, allowing non-alpha- - betic sorting (eg Revenues to appear above Expenses). - - o They can help hledger know your accounts' types (asset, liability, - equity, revenue, expense), enabling reports like balancesheet and in- - comestatement. - - o They help with account name completion (in hledger add, hledger-web, - hledger-iadd, ledger-mode, etc.) - - They are written as the word account followed by a hledger-style ac- - count name. Eg: - - account assets:bank:checking - - Ledger-style indented subdirectives are also accepted, but ignored: - - account assets:bank:checking - format subdirective ; currently ignored - - Account comments - Text following two or more spaces and ; at the end of an account direc- - tive line, and/or following ; on indented lines immediately below it, - form comments for that account. They are ignored except they may con- - tain 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 - - 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 jour- - nal. Usually you'll find that error later, as an extra account in bal- - ance reports, or an incorrect balance when reconciling. - - In strict mode, enabled with the -s/--strict flag, or when you run - hledger check accounts, hledger will report an error if any transaction - uses an account name that has not been declared by an account direc- - tive. Some notes: - - o The declaration is case-sensitive; transactions must use the correct - account name capitalisation. - - o The account directive's scope is "whole file and below" (see direc- - tives). This means it affects all of the current file, and any files - it includes, but not parent or sibling files. The position of ac- - count directives within the file does not matter, though it's usual - to put them at the top. - - o Accounts can only be declared in journal files, but will affect in- - cluded files of all types. - - o It's currently not possible to declare "all possible subaccounts" - with a wildcard; every account posted to must be declared. - - o If you use the --infer-equity flag, you will also need declarations - for the account names it generates. - - Account display order - Account directives also cause hledger to display accounts in a particu- - lar order, not just alphabetically. Eg, here is a conventional order- - ing for the top-level accounts: - - account assets - account liabilities - account equity - account revenues - account expenses - - Now hledger displays them in that order: - - $ hledger accounts - assets - liabilities - equity - revenues - expenses - - If there are undeclared accounts, those will be displayed last, in al- - phabetical order. - - Sorting is done within each group of sibling accounts, at each level of - the account tree. Eg, a declaration like account parent:child influ- - ences child's position among its siblings. - - Note, it does not affect parent's position; for that, you need an ac- - count parent declaration. - - Sibling accounts are always displayed together; hledger won't display - x:y in between a:b and a:c. - - An account directive both declares an account as a valid posting tar- - get, and declares its display order; you can't easily do one without - the other. - - Account types - hledger knows that in accounting there are three main account types: - - Asset A things you own - Liability L things you owe - Equity E owner's investment, - balances the two - above - - and two more representing changes in these: - - Revenue R inflows (also known - as Income) - Expense X outflows - - hledger also uses a couple of subtypes: - - Cash C liquid assets - Conversion V commodity conver- - sions equity - - As a convenience, hledger will detect these types automatically from - english account names. But it's better to declare them explicitly by - adding a type: tag in the account directives. The tag's value can be - any of the types or one-letter abbreviations above. - - Here is a typical set of account type declarations. Subaccounts will - inherit their parent's type, or can override it: - - 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 - - This enables the easy balancesheet, balancesheetequity, cashflow and - incomestatement reports, and querying by type:. - - Tips: - - o You can list accounts and their types, for troubleshooting: - - $ hledger accounts --types [ACCTPAT] [type:TYPECODES] [-DEPTH] [--positions] - - o It's a good idea to declare at least one account for each account - type. Having some types declared and some inferred can disrupt cer- - tain reports. - - o The rules for inferring types from account names are as follows (us- - ing Regular expressions). - If they don't work for you, just ignore them and declare your types - with type: tags. - - If account's name contains this case insensitive 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 - - o As mentioned above, subaccounts will inherit a type from their parent - account. To be precise, an account's type is decided by the first of - these that exists: - - 1. A type: declaration for this account. - - 2. A type: declaration in the parent accounts above it, preferring - the nearest. - - 3. An account type inferred from this account's name. - - 4. An account type inferred from a parent account's name, preferring - the nearest parent. - - 5. Otherwise, it will have no type. - - o Account aliases can disrupt account types. - - 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: - - o expanding shorthand account names to their full form, allowing easier - data entry and a less verbose journal - - o adapting old journals to your current chart of accounts - - o experimenting with new account organisations, like a new hierarchy - - o combining two accounts into one, eg to see their sum or difference on - one line - - o 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 cor- - rectly, but you can also generate invalid account names with them; more - on this below. - - See also Rewrite account names. - - 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 re- - place any occurrence of the old account name with the new one. Subac- - counts 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" - - 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 ex- - pression.) - - Eg: - - alias /REGEX/ = REPLACEMENT - - or: - - $ hledger --alias '/REGEX/=REPLACEMENT' ... - - Any part of an account name matched by REGEX will be replaced by RE- - PLACEMENT. 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. - - 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: - - o the nearest alias declaration before/above the entry is applied first - - o the next alias before/above that will be be applied next, and so on - - o aliases defined after/below the entry do not affect it. - - This gives nearby aliases precedence over distant ones, and helps pro- - vide semantic stability - aliases will keep working the same way inde- - pendent 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. - - 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. In- - cluding 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 - - end aliases directive - You can clear (forget) all currently defined aliases (seen in the jour- - nal so far, or defined on the command line) with this directive: - - end aliases - - 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 exam- - ple, 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 - - 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 ef- - fect. - - 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, renam- - ing it by an alias could prevent or alter that. - - If you are using account aliases and the type: query is not matching - accounts as you expect, try troubleshooting with the accounts command, - eg something like: - - $ hledger accounts --types -1 --alias assets=bassetts - - commodity directive - The commodity directive performs several functions: - - 1. It declares which commodity symbols may be used in the journal, en- - abling useful error checking with strict mode or the check command. - See Commodity error checking below. - - 2. It declares how all amounts in this commodity should be displayed, - eg how many decimals to show. See Commodity display style above. - - 3. (If no decimal-mark directive is in effect:) It sets the decimal - mark to expect (period or comma) when parsing amounts in this com- - modity, in this file and files it includes, from the directive until - end of current file. See Decimal marks above. - - 4. It declares the precision with which this commodity's amounts should - be compared when checking for balanced transactions, anywhere in - this file and files it includes, until end of current file. - - Declaring commodities solves several common parsing/display problems, - so we recommend it. - - Note that effects 3 and 4 above end at the end of the directive's file, - and will not affect sibling or parent files. So if you are relying on - them (especially 4) and using multiple files, placing your commodity - directives in a top-level parent file might be important. Or, keep - your decimal marks unambiguous and your entries well balanced and pre- - cise. - - (Related: #793) - - Commodity directive syntax - A commodity directive is normally the word commodity followed by a sam- - ple amount (and optionally a comment). Only the amount's symbol and - the number's format is significant. Eg: - - commodity $1000.00 - commodity 1.000,00 EUR - commodity 1 000 000.0000 ; the no-symbol commodity - - Commodities do not have tags (tags in the comment will be ignored). - - A commodity directive's sample amount must always include a period or - comma decimal mark (this rule helps disambiguate decimal marks and - digit group marks). If you don't want to show any decimal digits, - write the decimal mark at the end: - - commodity 1000. AAAA ; show AAAA with no decimals - - Commodity symbols containing spaces, numbers, or punctuation must be - enclosed in double quotes, as usual: - - commodity 1.0000 "AAAA 2023" - - Commodity directives normally include a sample amount, but can declare - only a symbol (ie, just function 1 above): - - commodity $ - commodity INR - commodity "AAAA 2023" - commodity "" ; the no-symbol commodity - - Commodity directives may also be written with an indented format subdi- - rective, 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 - - Commodity error checking - In strict mode (-s/--strict) (or when you run hledger check commodi- - ties), 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). - - 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). - - include directive - You can pull in the content of additional files by writing an include - directive, like this: - - include SOMEFILE - - This has the same effect as if SOMEFILE's content was inlined at this - point. (With any include directives in SOMEFILE processed similarly, - recursively.) - - Only journal files can include other files. They can include journal, - timeclock or timedot files, but not CSV files. - - If the file path begins with a tilde, that means your home directory: - include ~/main.journal. - - If it begins with a slash, it is an absolute path: include - /home/user/main.journal. Otherwise it is relative to the including - file's folder: include ../finances/main.journal. - - Also, the path may have a file type prefix to force a specific file - format, overriding the file extension(s) (as described in Data for- - mats): include timedot:notes/2023.md. - - The path may contain glob patterns to match multiple files. hledger's - globs are similar to zsh's: ? to match any character; [a-z] to match - any character in a range; * to match zero or more characters that - aren't a path separator (like /); ** to match zero or more subdirecto- - ries and/or zero or more characters at the start of a file name; etc. - Also, hledger's globs always exclude the including file itself. So, - you can do - - o include *.journal to include all other journal files in the current - directory (excluding dot files) - - o include **.journal to include all other journal files in this direc- - tory and below (excluding dot directories/files) - - o include timelogs/2???.timedot to include all timedot files named like - a year number. - - There is a limitation: hledger's globs always exclude paths involving - dot files or dot directories. This is a workaround for unavoidable dot - directory traversal; you can disable it and revert to older behaviour - with the --old-glob flag, for now. - - If you are using many, or deeply nested, include files, and have an er- - ror that's hard to pinpoint: a good troubleshooting command is hledger - files --debug=6 (or 7). - - P directive - The P directive declares a market price, which is a conversion rate be- - tween 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. Ex- - amples: - - # 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. - - 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. - - tag directive - tag TAGNAME - - This directive can be used to declare a limited set of tag names al- - lowed in tags. TAGNAME should be a valid tag name (no spaces). Eg: - - tag item-id - - Any indented subdirectives are currently ignored. - - The "tags" check will report an error if any undeclared tag name is - used. It is quite easy to accidentally create a tag through normal use - of colons in comments; if you want to prevent this, you can declare and - check your tags . - - Periodic transactions - The ~ directive declares a "periodic rule" which generates temporary - extra transactions, usually recurring at some interval, when hledger is - run with the --forecast flag. These "forecast transactions" are useful - for forecasting future activity. They exist only for the duration of - the report, and only when --forecast is used; they are not saved in the - journal file by hledger. - - Periodic rules also have a second use: with the --budget flag they set - budget goals for budgeting. - - Periodic rules can be a little tricky, so before you use them, read - this whole section, or at least the following tips: - - 1. Two spaces accidentally added or omitted will cause you trouble - - read about this below. - - 2. For troubleshooting, show the generated transactions with hledger - print --forecast tag:generated or hledger register --forecast - tag:generated. - - 3. Forecasted transactions will begin only after the last non-fore- - casted 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 im- - provement, 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. - - 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-pe- - riod reports, just interpreted differently; there, it specifies report - periods; here it specifies recurrence dates (the periods' start dates). - - 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 re- - sults 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. - - 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 acciden- - tally 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, - - o Do write two spaces between your period expression and your transac- - tion description, if any. - - o Don't accidentally write two spaces in the middle of your period ex- - pression. - - Auto postings - The = directive declares an "auto posting rule", which adds extra post- - ings to existing transactions. (Remember, postings are the account - name & amount lines below a transaction's date & description.) - - In the journal, an auto posting rule looks quite like a transaction, - but instead of date and description it has = (mnemonic: "match") and a - query, like this: - - = QUERY - ACCOUNT AMOUNT - ... - - Queries are just like command line queries; an account name substring - is most common. Query terms containing spaces should be enclosed in - single or double quotes. - - Each = rule works like this: when hledger is run with the --auto flag, - wherever the QUERY matches a posting in the journal, the rule's post- - ings are added to that transaction, immediately below the matched post- - ing. Note these generated postings are temporary, existing only for - the duration of the report, and only when --auto is used; they are not - saved in the journal file by hledger. - - The postings can contain the special string %account which will be ex- - panded to the account name of the matched account. - - Generated postings' amounts can depend on the matched posting's amount. - So auto postings can be useful for, eg, adding tax postings with a - standard percentage. AMOUNT can be: - - o a number with no commodity symbol, like 2. The matched posting's - commodity symbol will be added to this. - - o a normal amount with a commodity symbol, like $2. This will be used - as-is. - - o an asterisk followed by a number, like *2. This will multiply the - matched posting's amount (and total price, if any) by the number. - - o an asterisk followed by an amount with commodity symbol, like *$2. - This multiplies and also replaces the commodity symbol with this new - one. - - Some examples: - - ; every time I buy food, schedule a dollar donation - = expenses:food - (liabilities:charity) $-1 - - ; when I buy a gift, also deduct that amount from a budget envelope subaccount - = expenses:gifts - assets:checking:gifts *-1 - assets:checking *1 - - 2017/12/1 - expenses:food $10 - assets:checking - - 2017/12/14 - expenses:gifts $20 - assets:checking - - $ hledger print --auto - 2017-12-01 - expenses:food $10 - assets:checking - (liabilities:charity) $-1 - - 2017-12-14 - expenses:gifts $20 - assets:checking - assets:checking:gifts -$20 - assets:checking $20 - - Note that depending fully on generated data such as this has some draw- - backs - it's less portable, less future-proof, less auditable by oth- - ers, and less robust (eg your balance assertions will depend on whether - you use or don't use --auto). An alternative is to use auto postings - in "one time" fashion - use them to help build a complex journal entry, - view it with hledger print --auto, and then copy that output into the - journal file to make it permanent. - - 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). - - 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. - - Auto postings and transaction balancing / inferred amounts / balance asser- - tions - Currently, auto postings are added: - - o after missing amounts are inferred, and transactions are checked for - balancedness, - - o 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. - - Auto posting tags - Automated postings will have some extra tags: - - o generated-posting:= QUERY - shows this was generated by an auto post- - ing rule, and the query - - o _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: - - o modified: - this transaction was modified - - o _modified: - a hidden tag not appearing in the comment; this transac- - tion was modified "just now". - - Auto postings on forecast transactions only - Tip: you can can make auto postings that will apply to forecast trans- - actions but not recorded transactions, by adding tag:_generated-trans- - action to their QUERY. This can be useful when generating new journal - entries to be saved in the journal. - - 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. - - 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 assign- - ment). - - Downsides: using balance assignments makes your journal less explicit; - to know the exact amount posted, you have to run hledger or do the cal- - culations yourself, instead of just reading it. Also balance assign- - ments' forcing of balances can hide errors. These things make your fi- - nancial data less portable, less future-proof, and less trustworthy in - an audit. - - Balance assignments and costs - A cost in a balance assignment will cause the calculated amount to have - that cost attached: - - 2019/1/1 - (a) = $1 @ 2 - - $ hledger print --explicit - 2019-01-01 - (a) $1 @ 2 = $1 @ 2 - - 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. - - Bracketed posting dates - For setting posting dates and secondary posting dates, Ledger's brack- - eted 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 syn- - tax, 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. - - 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 jour- - nal. This effect lasts until the next D directive, or the end of the - current file. - - For compatibility/historical reasons, D also acts like a commodity di- - rective (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 deci- - mal 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 di- - rective 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 usu- - ally 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. - - 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 direc- - tive 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 included 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. - - 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 subse- - quent 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 trust- - worthy in an audit. Such dates can get separated from their corre- - sponding Y directive, eg when evaluating a region of the journal in - your editor. A missing Y directive makes reports dependent on today's - date. - - Secondary dates - A secondary date is written after the primary date, following an equals - sign: DATE1=DATE2. If the year is omitted, the primary date's year is - assumed. When running reports, the primary (left side) date is used by - default, but with the --date2 flag (--aux-date or--effective also work, - for Ledger users), the secondary (right side) date will be used in- - stead. - - The meaning of secondary dates is up to you. Eg it could be "primary - is the bank's clearing date, secondary is the date the transaction was - initiated, if different". - - In practice, this feature usually adds confusion: - - o You have to remember the primary and secondary dates' meaning, and - follow that consistently. - - o It splits your bookkeeping into two modes, and you have to remember - which mode is appropriate for a given report. - - o Usually your balance assertions will work with only one of these - modes. - - o It makes your financial data more complicated, less portable, and - less clear in an audit. - - o It interacts with every feature, creating an ongoing cost for imple- - mentors. - - o It distracts new users and supporters. - - o Posting dates are simpler and work better. - - So secondary dates are officially deprecated in hledger, remaining only - as a Ledger compatibility aid; we recommend using posting dates in- - stead. - - Star comments - Lines beginning with * (star/asterisk) are also comment lines. This - feature allows Emacs users to insert org headings in their journal, al- - lowing 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. - - Valuation expressions - Ledger allows a valuation function or value to be written in double - parentheses after an amount. hledger ignores these. - - Virtual postings - A posting with parentheses around the account name, like (some:account) - 10, is called an unbalanced virtual posting. These postings do not - participate in transaction balancing. (And if you write them without - an amount, a zero amount is always inferred.) These can occasionally - be convenient for special circumstances, but they violate double entry - bookkeeping and make your data less portable across applications, so - many people avoid using them at all. - - A posting with brackets around the account name ([some:account]) is - called a balanced virtual posting. The balanced virtual postings in a - transaction must add up to zero, just like ordinary postings, but sepa- - rately from them. These are not part of double entry bookkeeping ei- - ther, 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. - - 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. - - Other cost/lot notations - A slight digression for Ledger and Beancount users. - - Ledger has a number of cost/lot-related notations: - - o @ UNITCOST and @@ TOTALCOST - - o expresses a conversion rate, as in hledger - - o when buying, also creates a lot that can be selected at selling - time - - o (@) UNITCOST and (@@) TOTALCOST (virtual cost) - - o like the above, but also means "this cost was exceptional, don't - use it when inferring market prices". - - o {=UNITCOST} and {{=TOTALCOST}} (fixed price) - - o when buying, means "this cost is also the fixed value, don't let it - fluctuate in value reports" - - o {UNITCOST} and {{TOTALCOST}} (lot price) - - o can be used identically to @ UNITCOST and @@ TOTALCOST, also cre- - ates a lot - - o when selling, combined with @ ..., selects an existing lot by its - cost basis. Does not check if that lot is present. - - o [YYYY/MM/DD] (lot date) - - o when buying, attaches this acquisition date to the lot - - o when selling, selects a lot by its acquisition date - - o (SOME TEXT) (lot note) - - o when buying, attaches this note to the lot - - o when selling, selects a lot by its note - - Currently, hledger - - o accepts any or all of the above in any order after the posting amount - - o supports @ and @@ - - o treats (@) and (@@) as synonyms for @ and @@ - - o and ignores the rest. (This can break transaction balancing.) - - Beancount has simpler notation and different behaviour: - - o @ UNITCOST and @@ TOTALCOST - - o expresses a cost without creating a lot, as in hledger - - o when buying (acquiring) or selling (disposing of) a lot, and com- - bined with {...}: is not used except to document the cost/selling - price - - o {UNITCOST} and {{TOTALCOST}} - - o when buying, expresses the cost for transaction balancing, and also - creates a lot with this cost basis attached - - o when selling, - - o selects a lot by its cost basis - - o raises an error if that lot is not present or can not be selected - unambiguously (depending on booking method configured) - - o expresses the selling price for transaction balancing - - o {}, {YYYY-MM-DD}, {"LABEL"}, {UNITCOST, "LABEL"}, {UNITCOST, - YYYY-MM-DD, "LABEL"} - - o when selling, other combinations of date/cost/label, like the - above, are accepted for selecting the lot. - - Currently, hledger - - o supports @ and @@ - - o accepts the {UNITCOST}/{{TOTALCOST}} notation, but ignores it - - o and rejects the rest. - -CSV - hledger can read transactions from CSV (comma-separated values) files. - More precisely, it can read DSV (delimiter-separated values), from a - file or standard input. Comma-separated, semicolon-separated and - tab-separated are the most common variants, and hledger will recognise - these three automatically based on a .csv, .ssv or .tsv file name ex- - tension or a csv:, ssv: or tsv: file path prefix. - - (To learn about producing CSV or TSV output, see Output format.) - - 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 attrib- - utes. - - By default, hledger expects this rules file to be named like the CSV - file, with an extra .rules extension added, in the same directory. Eg - when asked to read foo/FILE.csv, hledger looks for foo/FILE.csv.rules. - You can specify a different rules file with the --rules option. - - At minimum, the rules file must identify the date and amount fields, - and often it also specifies the date format and how many header lines - there are. Here's a simple CSV file and a rules file for it: - - Date, Description, Id, Amount - 12/11/2019, Foo, 123, 10.23 - - # basic.csv.rules - skip 1 - fields date, description, , amount - date-format %d/%m/%Y - - $ hledger print -f basic.csv - 2019-11-12 Foo - expenses:unknown 10.23 - income:unknown -10.23 - - There's an introductory Tutorial: Import CSV data on hledger.org, and - more CSV rules examples below, and a larger collection at - https://github.com/simonmichael/hledger/tree/master/examples/csv. - - 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 - archive optionally enable an archive of imported files - encoding optionally declare which text encoding the - data has - separator declare the field separator, instead of rely- - ing 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 op- - tionally 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/as- - signments to generate - include inline another CSV rules file - - Working with CSV tips can be found below, including How CSV rules are - evaluated. - - 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 pro- - vides some extra features. For one, the data file can be missing, - without causing an error; it is just considered empty. - - For more flexibility, add a source rule, which lets you specify a dif- - ferent data file: - - source ./Checking1.csv - - If the file does not exist, it is just considered empty, without rais- - ing an error. - - If you specify just a file name with no path, hledger will look for it - in the ~/Downloads folder: - - source Checking1.csv - - You can use a glob pattern, to avoid specifying the file name exactly: - - source Checking1*.csv - - This has another benefit: if the pattern matches multiple files, - hledger will read the newest (most recently modified) one. This avoids - problems if you have downloaded a file multiple times without cleaning - up. - - All this enables a convenient workflow where can you just download CSV - files, then run hledger import rules/*. - - See also "Working with CSV > Reading files specified by rule". - - Data cleaning / generating commands - After source's file pattern, you can write | (pipe) and a data cleaning - command. If hledger's CSV rules aren't enough, you can pre-process the - downloaded data here with a shell command or script, to make it more - suitable for conversion. The command will be executed by your default - shell, in the directory of the rules file, will receive the data file's - content as standard input, and should output zero or more lines of - character-separated-values, suitable for conversion by the CSV rules. - - Examples: - - source ./paypal.json | paypalcsv - source data/simplefin.json | simplefincsv - 'chase.*card' - source OfxDownload*.csv | grep -vE '^(([^,]*,){6}[^,]*|)$' | sort -t, -n +2 - source History_for_Account_Z20144832*.csv # | grep -E '^([^,]*,){12}[^,]*$' | sed -E -e 's/^ //' -e 's/\.([0-9]),/.\10,/g' -e 's/,([0-9]+),/,\1.00,/g' - - Or, after source you can write | and a data generating command (with no - file pattern before the |). This command receives no input, and should - output zero or more lines of character-separated values, suitable for - conversion by the CSV rules. - - Examples: - - source | paypaljson | paypalcsv - source | paypalcsv data/paypal.json - source | simplefinjson >data/simplefin.json && simplefincsv data/simplefin.json 'chase.*card' - source | simplefincsv data/simplefin.json 'unify.*checking' - - (paypal* and simplefin* scripts are in bin/) - - Whenever hledger runs one of these commands, it will echo the command - on stderr. If the command produces error output, but exits success- - fully, hledger will show the error output as a warning. If the command - fails, hledger will fail and show the error output in the error mes- - sage. - - Added in 1.50; experimental. - - archive - With archive added to a rules file, the import command will archive - each successfully processed data file or data command output in a - nearby data/ directory. The archive file name will be based on the - rules file and the data file's modification date and extension (or for - a data-generating command, the current date and the ".csv" extension). - The original data file, if any, will be removed. - - Also, in this mode import will prefer the oldest file matched by the - source rule's glob pattern, not the newest. (So if there are multiple - downloads, they will be imported and archived oldest first.) - - Archiving is optional, but it can be useful for troubleshooting your - CSV rules, regenerating entries with improved rules, checking for vari- - ations in your bank's CSV, etc. - - Added in 1.50; experimental. - - encoding - encoding ENCODING - - hledger normally expects non-ascii text to be using the system locale's - text encoding. If you need to read CSV files which have some other en- - coding, you can do it by adding encoding ENCODING to your CSV rules. - Eg: encoding iso-8859-1. - - The following encodings are supported: - - ascii, utf-8, utf-16, utf-32, iso-8859-1, iso-8859-2, iso-8859-3, - iso-8859-4, iso-8859-5, iso-8859-6, iso-8859-7, iso-8859-8, iso-8859-9, - iso-8859-10, iso-8859-11, iso-8859-13, iso-8859-14, iso-8859-15, - iso-8859-16, cp1250, cp1251, cp1252, cp1253, cp1254, cp1255, cp1256, - cp1257, cp1258, koi8-r, koi8-u, gb18030, macintosh, jis-x-0201, - jis-x-0208, iso-2022-jp, shift-jis, cp437, cp737, cp775, cp850, cp852, - cp855, cp857, cp860, cp861, cp862, cp863, cp864, cp865, cp866, cp869, - cp874, cp932. - - Added in 1.42. - - separator - You can use the separator rule to read other kinds of character-sepa- - rated 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 automat- - ically, and you won't need this rule. - - 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. - - 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/pack- - age/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 - - Note currently there is no locale awareness for things like %b, and - setting LC_TIME won't help. - - 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. - - 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 transac- - tions in correct order. - - # same-day CSV records are newest first - newest-first - - 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 - - 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. - - 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: - - o There must be least two items in the list (at least one comma). - - o Field names may not contain spaces. Spaces before/after field names - are optional. - - o Field names may contain _ (underscore) or - (hyphen). - - o 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 re- - placed 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 "bal- - ance" field balance_ to avoid directly setting hledger's balance field - (and generating a balance assertion). - - 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 inter- - polate 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: - - o Interpolation strips outer whitespace (so a CSV value like " 1 " be- - comes 1 when interpolated) (#1051). - - o Interpolations always refer to a CSV field - you can't interpolate a - hledger field. (See Referencing other fields below). - - 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 auto- - matically recognise column headings in a CSV file), by writing arbi- - trary 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 as- - signment, 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 hap- - pens when you assign values to them: - - date field - Assigning to date sets the transaction date. - - date2 field - date2 sets the transaction's secondary date, if any. - - status field - status sets the transaction's status, if any. - - code field - code sets the transaction's code, if any. - - description field - description sets the transaction's description, if any. - - comment field - comment sets the transaction's comment, if any. - - commentN, where N is a number, sets the Nth posting's comment. - - You can assign multi-line comments by writing literal \n in the code. - A comment starting with \n will begin on a new line. - - Comments can contain tags, as usual. - - Posting comments can also contain a posting date. A secondary date, or - a year-less date, will be ignored. - - 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"). - - amount field - There are several ways to set posting amounts from CSV, useful in dif- - ferent 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: - - o 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". - - o 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. - - o 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 noth- - ing. - - o hledger assumes both CSV fields contain unsigned numbers, and it - automatically negates the amount-out values. - - o 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 com- - plex transactions. The posting numbers don't have to be consecu- - tive; 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 flexibil- - ity, use an if rule to set amounts conditionally. See "Working with - CSV > Setting amounts" below for more on this and on amount-setting - generally. - - 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. - - balance field - balanceN sets a balance assertion amount (or if the posting amount is - left empty, a balance assignment) on posting N. - - balance is a compatibility spelling for hledger <1.17; it is equivalent - to balance1. - - You can adjust the type of assertion/assignment with the balance-type - rule (see below). - - See the Working with CSV tips below for more about setting amounts and - currency. - - if block - Rules can be applied conditionally, depending on patterns in the CSV - data. This allows flexibility; in particular, it is how you can cate- - gorise transactions, selecting an appropriate account name based on - their description (for example). There are two ways to write condi- - tional 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 ap- - plied. They are usually field assignments, but the following special - rules may also be used within an if block: - - o skip - skips the matched CSV record (generating no transaction from - it) - - o 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 - - Matchers - There are two kinds of matcher: - - 1. A whole record matcher is simplest: it is just a word, single-line - text fragment, or other regular expression, which hledger will try - to match case-insensitively anywhere within the CSV record. - Eg: whole foods. - - 2. A field matcher has a percent-prefixed CSV field number or name be- - fore the pattern. - Eg: %3 whole foods or %description whole foods. - hledger will try to match the pattern just within the named CSV field. - - When using these, there's two things to be aware of: - - 1. Whole record matchers don't see the exact original record; they see - a reconstruction of it, in which values are comma-separated, and - quotes enclosing values and whitespace outside those quotes are re- - moved. - Eg when reading an SSV record like: 2023-01-01 ; "Acme, Inc. " ; 1,000 - the whole record matcher sees instead: 2023-01-01,Acme, Inc. ,1,000 - - 2. Field matchers expect either a CSV field number, or a CSV field name - declared with fields. (Don't use a hledger field name here, unless - it is also a CSV field name.) A non-CSV field name will cause the - matcher to match against "" (the empty string), and does not raise - an error, allowing easier reuse of common rules with different CSV - files. - - You can also prefix a matcher with ! (and optional space) to negate it. - Eg ! whole foods, ! %3 whole foods, !%description whole foods will - match if "whole foods" is NOT present. Added in 1.32. - - The pattern is, as usual in hledger, a POSIX extended regular expres- - sion that also supports GNU word boundaries (\b, \B, \<, \>) and noth- - ing else. If you have trouble with it, see "Regular expressions" in - the hledger manual (https://hledger.org/hledger.html#regular-expres- - sions). - - Multiple matchers - When an if block has multiple matchers, each on its own line, - - o By default they are OR'd (any of them can match). - - o Matcher lines beginning with & (or &&, since 1.42) are AND'ed with - the matcher above (all in the AND'ed group must match). - - o Matcher lines beginning with & ! (since 1.41, or && !, since 1.42) - are first negated and then AND'ed with the matcher above. - - You can also combine multiple matchers one the same line separated by - && (AND) or && ! (AND NOT). Eg %description amazon && %date 2025-01-01 - will match only when the description field contains "amazon" and the - date field contains "2025-01-01". Added in 1.42. - - Match groups - Added in 1.32 - - Matchers can define match groups: parenthesised portions of the regular - expression which are available for reference in field assignments. - Groups are enclosed in regular parentheses (( and )) and can be nested. - Each group is available in field assignments using the token \N, where - N is an index into the match groups for this conditional block (e.g. - \1, \2, etc.). - - Example: Warp credit card payment postings to the beginning of the - billing period (Month start), to match how they are presented in state- - ments, 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 - - if table - "if tables" are an alternative to if blocks; they can express many - matchers and field assignments in a more compact tabular format, like - this: - - if,HLEDGERFIELD1,HLEDGERFIELD2,... - MATCHERA,VALUE1,VALUE2,... - MATCHERB && MATCHERC,VALUE1,VALUE2,... (*since 1.42*) - ; Comment line that explains MATCHERD - MATCHERD,VALUE1,VALUE2,... - - - The first character after if is taken to be this if table's field sepa- - rator. It is unrelated to the separator used in the CSV file. It - should be a non-alphanumeric character like , or | that does not appear - anywhere else in the table (it should not be used in field names or - matchers or values, and it cannot be escaped with a backslash). - - Each line must contain the same number of separators; empty values are - allowed. Whitespace can be used in the matcher lines for readability - (but not in the if line, currently). You can use the comment lines in - the table body. The table must be terminated by an empty line (or end - of file). - - An if table like the above is interpreted as follows: try all of the - lines with matchers; whenever a line with matchers succeeds, assign all - of the values on that line to the corresponding hledger fields; If mul- - tiple lines match, later lines will override fields assigned by the - earlier ones - just like the sequence of if blocks would behave. - - If table presented above is equivalent to this sequence of if blocks: - - if MATCHERA - HLEDGERFIELD1 VALUE1 - HLEDGERFIELD2 VALUE2 - ... - - if MATCHERB && MATCHERC - HLEDGERFIELD1 VALUE1 - HLEDGERFIELD2 VALUE2 - ... - - ; Comment line which explains MATCHERD - if MATCHERD - HLEDGERFIELD1 VALUE1 - HLEDGERFIELD2 VALUE2 - ... - - Example: - - if,account2,comment - atm transaction fee,expenses:business:banking,deductible? check it - %description groceries,expenses:groceries, - ;; Comment line that desribes why this particular date is special - 2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out - - 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 - - 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 - - Working with CSV - Some tips: - - 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. - - 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: - - o Values may be enclosed in double quotes, or not. Enclosing in single - quotes is not allowed. (Eg 'A','B' is rejected.) - - o When values are enclosed in double quotes, spaces outside the quotes - are not allowed. (Eg "A", "B" is rejected.) - - o 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 trans- - form it before reading with hledger. Try using sed, or a more permis- - sive CSV parser like python's csv lib. - - 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. - - 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 - - Reading multiple CSV files - If you use multiple -f options to read multiple CSV files at once, - hledger will look for a correspondingly-named rules file for each CSV - file. But if you specify a rules file with --rules, that rules file - will be used for all the CSV files. - - 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 file- - names 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 transac- - tions - - 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 noth- - ing, 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. - - Valid transactions - After reading a CSV file, hledger post-processes and validates the gen- - erated 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 as- - sertions generated from CSV right away, pipe into another hledger: - - $ hledger -f file.csv print | hledger -f- print - - 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: - - o https://hledger.org/cookbook.html#setups-and-workflows - - o https://plaintextaccounting.org -> data import/conversion - - Setting amounts - Continuing from amount field above, here are more tips for amount-set- - ting: - - 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 usu- - ally 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 con- - taining 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. - - 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): - - o If an amount value begins with a plus sign: - that will be removed: +AMT becomes AMT - - o If an amount value is parenthesised: - it will be de-parenthesised and sign-flipped: (AMT) becomes -AMT - - o 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 - - o If an amount value contains just a sign (or just a set of parenthe- - ses): - 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. - - 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. - - Amount decimal places - When you are reading CSV data, eg with a command like hledger -f - foo.csv print, hledger will infer each commodity's decimal precision - (and other commodity display styles) from the amounts - much as when - reading a journal file without commodity directives (see the link). - - Note, the commodity styles are not inferred from the numbers in the - original CSV data; rather, they are inferred from the amounts generated - by the CSV rules. - - When you are importing CSV data with the import command, eg hledger im- - port foo.csv, there's another step: import tries to make the new en- - tries conform to the journal's existing styles. So for each commodity - - let's say it's EUR - import will choose: - - 1. the style declared for EUR by a commodity directive in the journal - - 2. otherwise, the style inferred from EUR amounts in the journal - - 3. otherwise, the style inferred from EUR amounts generated by the CSV - rules. - - TLDR: if import is not generating the precisions or styles you want, - add a commodity directive to specify them. - - 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 lit- - eral "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 - - How CSV rules are evaluated - Here's how to think of CSV rules being evaluated. If you get a confus- - ing error while reading a CSV file, it may help to try to understand - which of these steps is failing: - - 1. Any included rules files are inlined, from top to bottom, depth - first (scanning each included file for further includes, recur- - sively, before proceeding). - - 2. Top level rules (date-format, fields, newest-first, skip etc) are - read, top to bottom. "Top level rules" means non-conditional rules. - If a rule occurs more than once, the last one wins; except for - skip/end rules, where the first one wins. - - 3. The CSV file is read as text. Any non-ascii characters will be de- - coded using the text encoding specified by the encoding rule, other- - wise the system locale's text encoding. - - 4. Any top-level skip or end rule is applied. skip [N] immediately - skips the current or next N CSV records; end immediately skips all - remaining CSV records (not normally used at top level). - - 5. Now any remaining CSV records are processed. For each CSV record, - in file order: - - o Is there a conditional skip/end rule that applies for this record - ? Search the if blocks, from top to bottom, for a succeeding one - containing a skip or end rule. If found, skip the specified num- - ber of CSV records, then continue at 5. - Otherwise... - - o Do some basic validation on this CSV record (eg, check that it - has at least two fields). - - o For each hledger field (date, description, account1, etc.): - - 1. Get the field's assigned value, first searching top level as- - signments, made directly or by the fields rule, then assign- - ments made inside succeeding if blocks. If there are more - than one, the last one wins. - - 2. Compute the field's actual value (as text), by interpolating - any %CSVFIELD references within the assigned value; or by - choosing a default value if there was no assignment. - - o Generate a hledger transaction from the hledger field values, - parsing them if needed (eg from text to an amount). - - This is all done by the CSV reader, one of several readers hledger can - use to read transactions from an input file. When all input files have - been read successfully, their transactions are passed to whichever - hledger command the user specified. - - Well factored rules - Some things than can help reduce duplication and complexity in rules - files: - - o Extracting common rules usable with multiple CSV files into a com- - mon.rules, and adding include common.rules to each CSV's rules file. - - o Splitting if blocks into smaller if blocks, extracting the frequently - used parts. - - CSV rules examples - 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 neces- - sary 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 read- - ing directly from CSV, but they will be checked if these entries are - imported into a journal file. - - Coinbase - A simple example with some CSV from Coinbase. The spot price is - recorded using cost notation. The legacy amount field name conve- - niently 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 - - Amazon - Here we convert amazon.com order history, and use an if block to gener- - ate 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 - - 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: - -Timeclock - hledger can read time logs in the timeclock time logging format of - timeclock.el. As with Ledger, hledger's timeclock format is a sub- - set/variant of timeclock.el's. - - hledger's timeclock format was updated in hledger 1.43 and 1.50. If - your old time logs are rejected, you should adapt them to modern - hledger; for now, you can restore the pre-1.43 behaviour with the - --old-timeclock flag. - - Here the timeclock format in hledger 1.50+: - - # Comment lines like these, and blank lines, are ignored: - # comment line - ; comment line - * comment line - - # Lines beginning with b, h, or capital O are also ignored, for compatibility: - b SIMPLEDATE HH:MM[:SS][+-ZZZZ][ TEXT] - h SIMPLEDATE HH:MM[:SS][+-ZZZZ][ TEXT] - O SIMPLEDATE HH:MM[:SS][+-ZZZZ][ TEXT] - - # Lines beginning with i or o are are clock-in / clock-out entries: - i SIMPLEDATE HH:MM[:SS][+-ZZZZ] ACCOUNT[ DESCRIPTION][;COMMENT]] - o SIMPLEDATE HH:MM[:SS][+-ZZZZ][ ACCOUNT][;COMMENT] - - The date is a hledger simple date (YYYY-MM-DD or similar). The time - parts must use two digits. The seconds are optional. A + or - - four-digit time zone is accepted for compatibility, but currently ig- - nored; times are always interpreted as a local time. - - In clock-in entries (i), the account name is required. A transaction - description, separated from the account name by 2+ spaces, is optional. - A transaction comment, beginning with ;, is also optional. (Indented - following comment lines are also allowed, as in journal format.) - - In clock-out entries (o) have no description, but can have a comment if - you wish. A clock-in and clock-out pair form a "transaction" posting - some number of hours to an account - also known as a session. Eg: - - i 2015/03/30 09:00:00 session1 - o 2015/03/30 10:00:00 - - $ hledger -f a.timeclock print - 2015-03-30 * 09:00-10:00 - (session1) 1.00h - - Clock-ins and clock-outs are matched by their account/session name. If - a clock-out does not specify a name, the most recent unclosed clock-in - is closed. You can have multiple sessions active simultaneously. En- - tries are processed in the order they are parsed. Sessions spanning - more than one day are automatically split at day boundaries. - - Eg, the following time log: - - 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 - i 2015/04/02 12:00:00 another:account ; this demonstrates multple sessions being clocked in - i 2015/04/02 13:00:00 some account - o 2015/04/02 14:00:00 - o 2015/04/02 15:00:00 another:account - - generates these transactions: - - $ 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 - - 2015-04-02 * 12:00-15:00 ; this demonstrates multiple sessions being clocked in - (another:account) 3.00h - - 2015-04-02 * 13:00-14:00 - (some account) 1.00h - - 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: - - o use these shell aliases at the command line: - - alias ti='echo i `date "+%Y-%m-%d %H:%M:%S"` $* >>$TIMELOG' - alias to='echo o `date "+%Y-%m-%d %H:%M:%S"` >>$TIMELOG' - - o or Emacs's built-in timeclock.el, or the extended timeclock-x.el, and - perhaps the extras in ledgerutils.el - - o 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. - -Timedot - timedot format is hledger's human-friendly time logging format. Com- - pared to timeclock format, it is more convenient for quick, approxi- - mate, 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 as- - sumed, 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 trans- - action comment following a semicolon. - - After the date line are zero or more time postings, consisting of: - - o An account name - any hledger-style account name, optionally in- - dented. - - o Two or more spaces - required if there is an amount (as in journal - format). - - o A timedot amount, which can be - - o empty (representing zero) - - o 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. - - o 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. - - o Added in 1.32 one or more letters. These are like dots but they - also generate a tag t: (short for "type") with the letter as its - value, and a separate posting for each of the values. This pro- - vides a second dimension of categorisation, viewable in reports - with --pivot t. - - o 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: - - o Blank lines and lines beginning with # or ; are ignored. - - o 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). - - o Before the first date line, lines beginning with * (eg org headings) - are ignored. And from the first date line onward, Emacs org mode - heading prefixes at the start of lines (one or more *'s followed by a - space) will be ignored. This means the time log can also be a org - outline. - - Timedot files don't support directives like journal files. So a common - pattern is to have a main journal file (eg time.journal) that contains - any needed directives, and then includes the timedot file (include - time.timedot). - - 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 - -PART 3: REPORTING CONCEPTS -Time periods - Report start & end date - Most hledger reports will by default show the full time period repre- - sented by the journal. The report start date will be the earliest - transaction or posting date, and the report end date will be the latest - transaction, posting, or market price date. - - Often you will want to see a shorter period, such as the current month. - You can specify a start and/or end date with the -b/--begin, -e/--end, - or -p/--period options, or a date: query argument, described below. - All of these accept the smart date syntax, also described below. - - End dates are exclusive; specify the day after the last day you want to - see in the report. - - When dates are specified by multiple options, the last (right-most) op- - tion wins. And when date: queries and date options are combined, the - report period will be their intersection. - - Examples: - - -b 2016/3/17 - beginning on St. Patrick's day 2016 - - -e 12/1 - ending at the start of December 1st in the current year - - -p 'this month' - during the current month - - -p thismonth - same as above, spaces are optional - - -b 2023 - beginning on the first day of 2023 - - date:2023.. or date:2023- - same as above - - -b 2024 -e 2025 -p '2000 to 2030' date:2020-01 date:2020 : - during January 2020 (the smallest common period, with the -p overriding - -b and -e) - - Smart dates - In hledger's user interfaces (though not in the journal file), you can - optionally use "smart date" syntax. Smart dates can be written with - english words, can be relative, and can have parts omitted. Missing - parts are inferred as 1, when needed. Smart dates can be interpreted - as dates or periods depending on the context. - - Examples: - - 2004-01-01, 2004/10/1, 2004.9.1, 20240504, 2024Q1 : - Exact dates. The year must have at least four digits, the month must - be 1-12, the day must be 1-31, the separator can be - or / or . or - nothing. The q can be upper or lower case and the quarter number must - be 1-4. - - 2004-10 - start of month - - 2004q3 start of third quarter of 2004 - - q3 start of third quarter of current year - - 2004 start of year - - 10/1 or oct or october - October 1st in current year - - 21 21st day in current month - - yesterday, today, tomorrow - -1, 0, 1 days from today - - last/this/next day/week/month/quarter/year - -1, 0, 1 periods from the current period - - in n days/weeks/months/quarters/years - n periods from the current period - - n days/weeks/months/quarters/years ahead - n periods from the current period - - n days/weeks/months/quarters/years ago - -n periods from the current period - - 20181201 - 8 digit YYYYMMDD with valid year month and day - - 201812 6 digit YYYYMM with valid year and month - - Dates with no separators are allowed but might give surprising results - if mistyped: - - o 20181301 (YYYYMMDD with an invalid month) is parsed as an eight-digit - year - - o 20181232 (YYYYMMDD with an invalid day) gives a parse error - - o 201801012 (a valid YYYYMMDD followed by additional digits) gives a - parse error - - The meaning of relative dates depends on today's date. If you need to - test or reproduce old reports, you can use the --today option to over- - ride that. (Except for periodic transaction rules, which are not af- - fected by --today.) - - Report intervals - A report interval can be specified so that reports like register, bal- - ance or activity become multi-period, showing each subperiod as a sepa- - rate row or column. - - The following standard intervals can be enabled with command-line - flags: - - o -D/--daily - - o -W/--weekly - - o -M/--monthly - - o -Q/--quarterly - - o -Y/--yearly - - More complex intervals can be specified using -p/--period, described - below. - - Date adjustments - Start date adjustment - If you let hledger infer a report's start date, it will adjust the date - to the previous natural boundary of the report interval, for convenient - periodic reports. (If you don't want that, specify a start date.) - - For example, if the journal's first transaction is on january 10th, - - o hledger register (no report interval) will start the report on janu- - ary 10th. - - o hledger register --monthly will start the report on the previous - month boundary, january 1st. - - o hledger register --monthly --begin 1/5 will start the report on janu- - ary 5th [1]. - - Also if you are generating transactions or budget goals with periodic - transaction rules, their start date may be adjusted in a similar way - (in certain situations). - - End date adjustment - A report's end date is always adjusted to include a whole number of in- - tervals, so that the last subperiod has the same length as the others. - - For example, if the journal's last transaction is on february 20th, - - o hledger register will end the report on february 20th. - - o hledger register --monthly will end the report at the end of febru- - ary. - - o hledger register --monthly --end 2/14 also will end the report at the - end of february (overriding the requested end date). - - o hledger register --monthly --begin 1/5 --end 2/14 will end the report - on march 4th [1]. - - [1] Since hledger 1.29. - - Period headings - With non-standard subperiods, hledger will show "STARTDATE..ENDDATE" - headings. With standard subperiods (ie, starting on a natural interval - boundary), you'll see more compact headings, which are usually prefer- - able. (Though month names will be in english, currently.) - - So if you are specifying a start date and you want compact headings: - choose a start of year for yearly reports, a start of quarter for quar- - terly reports, a start of month for monthly reports, etc. (Remember, - you can write eg -b 2024 or 1/1 as a shortcut for a start of year, or - 2024-04 or 202404 or Apr for a start of month or quarter.) - - For weekly reports, choose a date that's a Monday. (You can try dif- - ferent dates until you see the short headings, or write eg -b '3 weeks - ago'.) - - Period expressions - The -p/--period option specifies a period expression, which is a com- - pact 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 syn- - onym - -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 "2009/1/1" the first day of 2009; equivalent to "2009/1/1 to - 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 - - 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" - - More complex report intervals - Some more complex intervals can be specified within period expressions, - such as: - - o biweekly (every two weeks) - - o fortnightly - - o bimonthly (every two months) - - o every day|week|month|quarter|year - - o every N days|weeks|months|quarters|years - - Weekly on a custom day: - - o every Nth day of week (th, nd, rd, or st are all accepted after the - number) - - o every WEEKDAYNAME (full or three-letter english weekday name, case - insensitive) - - Monthly on a custom day: - - o every Nth day [of month] (31st day will be adjusted to each month's - last day) - - o every Nth WEEKDAYNAME [of month] - - Yearly on a custom month and day: - - o every MM/DD [of year] (month number and day of month number) - - o every MONTHNAME DDth [of year] (full or three-letter english month - name, case insensitive, and day of month number) - - o 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 week" periods will go from Tue to Tue - -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" - - Multiple weekday intervals - This special form is also supported: - - o every WEEKDAYNAME,WEEKDAYNAME,... (full or three-letter english week- - day 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 weekday" dates will be Mon, Tue, Wed, Thu, Fri; periods will - be Mon, Tue, Wed, Thu, Fri-Sun - -p "every weekend- dates will be Sat, Sun; periods will be Sat, Sun-Fri - day" - -Depth - With the --depth NUM option (short form: -NUM), reports will show ac- - counts 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. So all of these are equivalent: - depth:2, --depth=2, -2. - - In place of a single number which limits the depth for all accounts, - you can also provide depth limits for specific accounts, by providing a - REGEX=DEPTH argument instead of just a DEPTH (since 1.41). For exam- - ple, --depth assets=2 (or depth:assets=2) will collapse accounts match- - ing the regular expression "assets" to depth 2. So assets:bank:savings - would be collapsed to assets:bank, but liabilities:bank:credit card - would not be affected. - - (If REGEX contains spaces or other special characters, enclose it in - quotes in the usual way. Eg: --depth 'credit card=2') - - Specific depth options and a general depth option can be combined. Eg - --depth assets=3 --depth expenses=2 --depth 1 would collapse accounts - containing "assets" to depth 3, accounts containing "expenses" to depth - 2, and all other accounts to depth 1. - - If an account is matched by more than one regular expression depth ar- - gument, the most specific (deepest) match will be used. For example, - with --depth assets=1 --depth savings=2, assets:bank:savings will be - collapsed to depth 2, not depth 1 (because "savings" matches a deeper - part of it than "assets" does). - -Queries - Many hledger commands accept query arguments, which restrict their - scope and let you report on a precise subset of your data. Here's a - quick overview of hledger's queries: - - o By default, a query argument is treated as a case-insensitive sub- - string pattern for matching account names. Eg: - - dining groceries - car:fuel - o Patterns containing spaces or other special characters must be en- - closed in single or double quotes: - - 'personal care' - o Patterns are actually regular expressions, so you can add regexp - metacharacters for more precision (or you may need to backslash-es- - cape certain characters; see "Regular expressions" above): - - '^expenses\b' - 'food$' - 'fuel|repair' - 'accounts (payable|receivable)' - o To match something other than the account name, you can add a query - type prefix, such as: - - date:202312- - status: - desc:amazon - cur:USD - cur:\\$ - amt:'>0' - acct:groceries (but acct: is the default, so we usually don't bother - writing it) - o To negate a query, add a not: prefix: - - not:status:'*' - not:desc:'opening|closing' - not:cur:USD - o Multiple query terms can be combined, as space-separated queries Eg: - hledger print date:2022 desc:amazon desc:amzn (show transactions - dated in 2022 whose description contains "amazon" or "amzn"). - o Or more flexibly as boolean queries. Eg: hledger print - expr:'date:2022 and (desc:amazon or desc:amzn) and not date:202210' - All hledger commands use the same query language, but different com- - mands may interpret the query in different ways. We haven't described - the commands yet (that's coming in PART 4: COMMANDS below) but here's - the gist of it: - - o Transaction-oriented commands (print, aregister, close, import, de- - scriptions..) try to match transactions (including the transaction's - postings). - - o Posting-oriented commands (register, balance, balancesheet, incomes- - tatement, accounts..) try to match postings. Postings inherit their - transaction's attributes for querying purposes, so transaction fields - like date or description can still be referenced in a posting query. - - o A few commands match in more specific ways. (Eg aregister, which has - a special first argument.) - - Query types - Here are the query types available: - - acct: query - acct:REGEX, or just REGEX - Match account names containing this case insensitive regular expres- - sion. - This is the default query type, so we usually don't bother writing the - "acct:" prefix. - - amt: query - 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.) amt: needs quotes to hide the less - than/greater than sign from the command line shell. - - 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 mag- - nitudes are compared, ignoring sign. - - Keep in mind that amt: matches posting amounts, not account balances. - - code: query - code:REGEX - Match by transaction code (eg check number). - - cur: query - cur:REGEX - Match postings or transactions including any amounts whose cur- - rency/commodity symbol is fully matched by REGEX. (Contrary to - hledger's usual infix matching. To do infix matching, write - .*REGEX.*.) Note, to match special characters which are regex-signifi- - cant, you need to escape them with \. And for characters which are - significant to your shell you will usually need one more level of es- - caping. Eg to match the dollar sign: cur:\\$ or cur:'\$' - - desc: query - desc:REGEX - Match transaction descriptions. - - date: query - date:PERIODEXPR - Match dates (or with the --date2 flag, secondary dates) within the - specified period. PERIODEXPR is a period expression with no report in- - terval. Examples: - date:2016, date:thismonth, date:2/1-2/15, date:2021-07-27..nextquarter. - - date2: query - date2:PERIODEXPR - If you use secondary dates: this matches secondary dates within the - specified period. It is not affected by the --date2 flag. - - depth: query - depth:[REGEXP=]N - Match (or display, depending on command) accounts at or above this - depth, optionally only for accounts matching a provided regular expres- - sion. See Depth for detailed rules. - - note: query - note:REGEX - Match transaction notes (the part of the description right of |, or the - whole description if there's no |). - - payee: query - payee:REGEX - Match transaction payee/payer names (the part of the description left - of |, or the whole description if there's no |). - - real: query - real:, real:0 - Match real or virtual postings respectively. - - status: query - status:, status:!, status:* - Match unmarked, pending, or cleared transactions respectively. - - type: query - type:TYPECODES - Match by account type (see Declaring accounts > Account types). TYPE- - CODES is one or more of the single-letter account type codes ALERXCV, - case insensitive. Note type:A and type:E will also match their respec- - tive subtypes C (Cash) and V (Conversion). Certain kinds of account - alias can disrupt account types, see Rewriting accounts > Aliases and - account types. - - tag: query - tag:NAMEREGEX[=VALREGEX] - Match by tag name, and optionally also by tag value. Note: - - o Both regular expressions do infix matching. If you need a complete - match, use ^ and $. - Eg: tag:'^fullname$', tag:'^fullname$=^fullvalue$ - - o To match values, ignoring names, do tag:.=VALREGEX - - o Accounts also inherit the tags of their parent accounts. - - o Postings also inherit the tags of their account and their transaction - . - - o Transactions also acquire the tags of their postings. - - Negative queries - not: query - not:QUERY - You can prepend not: to a query to negate the match. - Eg: not:equity, not:desc:apple - (Also, a trick: not:not:... can sometimes solve query problems conve- - niently.) - - Space-separated queries - When given multiple space-separated query terms, most commands select - things which match: - - o any of the description terms AND - - o any of the account terms AND - - o any of the status terms AND - - o all the other terms. - - The print command is a little different, showing transactions which: - - o match any of the description terms AND - - o have any postings matching any of the positive account terms AND - - o have no postings matching any of the negative account terms AND - - o match all the other terms. - - Boolean queries - You can write more complicated "boolean" query expressions, enclosed in - quotes and prefixed with expr:. These can combine subqueries with NOT, - AND, OR operators (case insensitive), and parentheses for grouping. - Eg, to show transactions involving both cash and expense accounts: - - hledger print expr:'cash AND expenses' - - The prefix and enclosing quotes are required, so don't write hledger - print cash AND expenses. That would be a space-separated query showing - transactions involving accounts with any of "cash", "and", "expenses" - in their names. - - You can write space-separated queries inside a boolean query, and they - will combine as described above, but it might be confusing and best - avoided. Eg these are equivalent, showing transactions involving cash - or expenses accounts: - - hledger print expr:'cash expenses' - hledger print cash expenses - - There is a restriction with date: queries: they may not be used inside - OR expressions. - - Actually, there are three types of boolean query: expr: for general - use, and any: and all: variants which can be useful with print. - - expr: query - expr:'QUERYEXPR' - For example, expr:'date:lastmonth AND NOT (food OR rent)' means "match - things which are dated in the last month and do not have food or rent - in the account name". - - When using expr: with transaction-oriented commands like print, post- - ing-oriented query terms like acct: and amt: are considered to match - the transaction if they match any of its postings. - So, hledger print expr:'cash and amt:>0' means "show transactions with - (at least one posting involving a cash account) and (at least one post- - ing with a positive amount)". - - any: query - any:'QUERYEXPR' - Like expr:, but when used with transaction-oriented commands like - print, it matches the transaction only if a posting can be matched by - all of QUERYEXPR. - So, hledger print any:'cash and amt:>0' means "show transactions where - at least one posting posts a positive amount to a cash account". - - all: query - all:'QUERYEXPR' - Like expr:, but when used with transaction-oriented commands like - print, it matches the transaction only if all postings are matched by - all of QUERYEXPR (and there is at least one posting). - So, hledger print all:'cash and amt:0' means "show transactions where - all postings involve a cash account and have a zero amount". - Or, hledger print all:'cash or checking' means "show transactions which - touch only cash and/or checking accounts". - - 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. - - Queries and account aliases - When account names are rewritten with --alias or alias, acct: will - match either the old or the new account name. - - Queries and valuation - When amounts are converted to other commodities in cost or value re- - ports, cur: and amt: match the old commodity symbol and the old amount - quantity, not the new ones. (Except in hledger 1.22, #1625.) - -Pivoting - Normally, hledger groups amounts and displays their totals by account - (name). With --pivot PIVOTEXPR, some other field's (or multiple - fields') value is used as a synthetic account name, causing different - grouping and display. PIVOTEXPR can be - - o any of these standard transaction or posting fields (their value is - substituted): status, code, desc, payee, note, acct, comm/cur, amt, - cost - - o or a tag name - - o or any combination of these, colon-separated. - - Some special cases: - - o Colons appearing in PIVOTEXPR or in a pivoted tag value will generate - account hierarchy. - - o When pivoting a posting has multiple values for a tag, the pivoted - value of that tag will be the first value. - - o When a posting has multiple commodities, the pivoted value of - "comm"/"cur" will be "". Also when an unrecognised tag name or field - is provided, its pivoted value will be "". (If this causes confusing - output, consider excluding those postings from the report.) - - Examples: - - 2016/02/16 Yearly Dues Payment - assets:bank account 2 EUR - income:dues -2 EUR ; member: John Doe, kind: Lifetime - - Normal balance report showing account names: - - $ hledger balance - 2 EUR assets:bank account - -2 EUR income:dues - -------------------- - 0 - - Pivoted balance report, using member: tag values instead: - - $ hledger balance --pivot member - 2 EUR - -2 EUR John Doe - -------------------- - 0 - - One way to show only amounts with a member: value (using a query): - - $ hledger balance --pivot member tag:member=. - -2 EUR John Doe - -------------------- - -2 EUR - - Another way (the acct: query matches against the pivoted "account - name"): - - $ hledger balance --pivot member acct:. - -2 EUR John Doe - -------------------- - -2 EUR - - Hierarchical reports can be generated with multiple pivot values: - - $ hledger balance Income:Dues --pivot kind:member - -2 EUR Lifetime:John Doe - -------------------- - -2 EUR - -Generating data - hledger can enrich the data provided to it, or generate new data, in a - number of ways. Mostly, this is done only if you request it: - - o Missing amounts or missing costs in transactions are inferred auto- - matically when possible. - - o The --infer-equity flag infers missing conversion equity postings - from @/@@ costs. - - o The --infer-costs flag infers missing costs from conversion equity - postings. - - o The --infer-market-prices flag infers P price directives from costs. - - o The --auto flag adds extra postings to transactions matched by auto - posting rules. - - o The --forecast option generates transactions from periodic transac- - tion rules. - - o The balance --budget report infers budget goals from periodic trans- - action rules. - - o Commands like close, rewrite, and hledger-interest generate transac- - tions or postings. - - o CSV data is converted to transactions by applying CSV conversion - rules.. etc. - - Such generated data is temporary, existing only at report time. You - can convert it to permanent recorded data by, eg, capturing the output - of hledger print and saving it in your journal file. This can some- - times be useful as a data entry aid. - - If you are curious what data is being generated and why, run hledger - print -x --verbose-tags. -x/--explicit shows inferred amounts and - --verbose-tags adds tags like generated-transaction (from periodic - rules) and generated-posting, modified (from auto posting rules). Sim- - ilar hidden tags (with an underscore prefix) are always present, also, - so you can always match such data with queries like tag:generated or - tag:modified. - -Forecasting - Forecasting, or speculative future reporting, can be useful for esti- - mating 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. - - --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 gen- - erate multiple recurring transactions, so by changing one rule you can - change many forecasted transactions. - - Forecast transactions usually start after ordinary transactions end. - By default, they begin after your latest-dated ordinary transaction, or - today, whichever is later, and they end six months from today. (The - exact rules are a little more complicated, and are given below.) - - This is the "forecast period", which need not be the same as the report - period. You can override it - eg to forecast farther into the future, - or to force forecast transactions to overlap your ordinary transactions - - by giving the --forecast option a period expression argument, like - --forecast=..2099 or --forecast=2023-02-15... Note that the = is re- - quired. - - Inspecting forecast transactions - print is the best command for inspecting and troubleshooting forecast - transactions. Eg: - - ~ monthly from 2022-12-20 rent - assets:bank:checking - expenses:rent $1000 - - $ hledger print --forecast --today=2023/4/21 - 2023-05-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - - 2023-06-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - - 2023-07-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - - 2023-08-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - - 2023-09-20 rent - ; generated-transaction: ~ monthly from 2022-12-20 - assets:bank:checking - expenses:rent $1000 - - Here there are no ordinary transactions, so the forecasted transactions - begin on the first occurrence after today's date. (You won't normally - use --today; it's just to make these examples reproducible.) - - 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 - - Forecast tags - Forecast transactions generated by --forecast have a hidden tag, _gen- - erated-transaction. So if you ever need to match forecast transac- - tions, you could use tag:_generated-transaction (or just tag:generated) - in a query. - - For troubleshooting, you can add the --verbose-tags flag. Then, visi- - ble generated-transaction tags will be added also, so you can view them - with the print command. Their value indicates which periodic rule was - responsible. - - Forecast period, in detail - Forecast start/end dates are chosen so as to do something useful by de- - fault in almost all situations, while also being flexible. Here are - (with luck) the exact rules, to help with troubleshooting: - - The forecast period starts on: - - o the later of - - o the start date in the periodic transaction rule - - o the start date in --forecast's argument - - o otherwise (if those are not available): the later of - - o the report start date specified with -b/-p/date: - - o the day after the latest ordinary transaction in the journal - - o otherwise (if none of these are available): today. - - The forecast period ends on: - - o the earlier of - - o the end date in the periodic transaction rule - - o the end date in --forecast's argument - - o otherwise: the report end date specified with -e/-p/date: - - o otherwise: 180 days (~6 months) from today. - - Forecast troubleshooting - When --forecast is not doing what you expect, one of these tips should - help: - - o Remember to use the --forecast option. - - o Remember to have at least one periodic transaction rule in your jour- - nal. - - o Test with print --forecast. - - o Check for typos or too-restrictive start/end dates in your periodic - transaction rule. - - o Leave at least 2 spaces between the rule's period expression and de- - scription fields. - - o Check for future-dated ordinary transactions suppressing forecasted - transactions. - - o Try setting explicit report start and/or end dates with -b, -e, -p or - date: - - o Try adding the -E flag to encourage display of empty periods/zero - transactions. - - o Try setting explicit forecast start and/or end dates with --fore- - cast=START..END - - o Consult Forecast period, in detail, above. - - o Check inside the engine: add --debug=2 (eg). - -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. - -Amount formatting - 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 preci- - sions, and bring other benefits such as error checking for commodity - symbols. Here's an example: - - # Set display styles (and decimal marks, for parsing, if there is no decimal-mark directive) - # for the $, EUR, INR and no-symbol commodities: - commodity $1,000.00 - commodity EUR 1.000,00 - commodity INR 9,99,99,999.00 - commodity 1 000 000.9455 - - But for convenience, if a commodity directive is not present, hledger - infers a commodity's display styles from its amounts as they are writ- - ten in the journal (excluding cost amounts and amounts in periodic - transaction rules or auto posting rules). It uses - - o the symbol placement and decimal mark of the first amount seen - - o the digit group marks of the first amount with digit group marks - - o and the maximum number of decimal digits seen across all amounts. - - And as fallback if no applicable amounts are found, it would use a de- - fault 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. - - 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 deci- - mal digits appears as "0". - - Trailing decimal marks - If you're wondering why your print report sometimes shows trailing dec- - imal marks, with no decimal digits; it does this when showing amounts - that have digit group marks but no decimal digits, to disambiguate them - and allow them to be re-parsed reliably (see Decimal marks). Eg: - - commodity $1,000.00 - - 2023-01-02 - (a) $1000 - - $ hledger print - 2023-01-02 - (a) $1,000. - - If this is a problem (eg when exporting to Ledger), you can avoid it by - disabling digit group marks, eg with -c/--commodity (for each affected - commodity): - - $ hledger print -c '$1000.00' - 2023-01-02 - (a) $1000 - - or by forcing print to always show decimal digits, with --round: - - $ hledger print -c '$1,000.00' --round=soft - 2023-01-02 - (a) $1,000.00 - - Amount parseability - More generally, hledger output falls into three rough categories, which - format amounts a little bit differently to suit different consumers: - - 1. "hledger-readable output" - should be readable by hledger (and by - humans) - - o This is produced by reports that show full journal entries: print, - import, close, rewrite etc. - - o It shows amounts with their original journal precisions, which may - not be consistent from one amount to the next. - - o It adds a trailing decimal mark when needed to avoid showing ambigu- - ous amounts. - - o It can be parsed reliably (by hledger and ledger2beancount at least, - but perhaps not by Ledger..) - - 2. "human-readable output" - usually for humans - - o This is produced by all other reports. - - o It shows amounts with standard display precisions, which will be con- - sistent within each commodity. - - o It shows ambiguous amounts unmodified. - - o 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 sin- - gle mark is a digit group mark). - - 3. "machine-readable output" - usually for other software - - o This is produced by all reports when an output format like csv, tsv, - json, or sql is selected. - - o It shows amounts as 1 or 2 do, but without digit group marks. - - o It can be parsed reliably (if needed, the decimal mark can be changed - with -c/--commodity-style). - -Cost reporting - In some transactions - for example a currency conversion, or a purchase - or sale of stock - one commodity is exchanged for another. In these - transactions there is a conversion rate, also called the cost (when - buying) or selling price (when selling). (In hledger docs we just say - "cost" generically for convenience.) With the -B/--cost flag, hledger - can show amounts "at cost", converted to the cost's commodity. - - 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: - - o It sacrifices some error checking. For example, if you accidentally - wrote 10 instead of 100, hledger would not be able to detect the mis- - take. - - o It is sensitive to the order of postings - if they were reversed, a - different entry would be inferred and reports would be different. - - o 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. - - 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 out- - put). Ie they will be displayed "at cost" or "at sale price". - - Some things to note: - - o Costs are attached to specific posting amounts in specific transac- - tions, and once recorded they do not change. This contrasts with - market prices, which are ambient and fluctuating. - - o Conversion to cost is performed before conversion to market value - (described below). - - 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: - - o The per-unit cost basis is not easy to read. - - o Instead of -B you must remember to type -B --infer-costs. - - o --infer-costs works only where hledger can identify the two eq- - uity:conversion postings and match them up with the two non-equity - postings. So writing the journal entry in a particular format be- - comes more important. More on this below. - - Inferring equity conversion postings - Can we go in the other direction ? Yes, if you have transactions writ- - ten 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 "eq- - uity:conversion:A-B:B" where A is the alphabetically first commodity - symbol. You can customise the "equity:conversion" part by declaring an - account with the V/Conversion account type. - - Note you will need to add account declarations for these to your jour- - nal, if you use check accounts or check --strict. - - 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 - preserv- - ing 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: - - o 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. - - o The add command does not yet accept this kind of entry (#2056). - - o This is the most verbose form. - - 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: - - o Two non-equity postings, in different commodities. Their order is - significant: the cost will be added to the first of them. - - o 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 conver- - sion posting's amount. Equity conversion accounts are: - - o any accounts declared with account type V/Conversion, or their sub- - accounts - - o otherwise, accounts named equity:conversion, equity:trade, or eq- - uity: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. - - 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. - -Value reporting - hledger can also show amounts "at market value", converted to some - other commodity using the market price or conversion rate on a certain - date. - - This is controlled by the --value=TYPE[,COMMODITY] option. We also - provide simpler -V and -X COMMODITY aliases for this, which are often - sufficient. The market prices are declared with a special P directive, - and/or they can be inferred from the costs recorded in transactions, by - using the --infer-market-prices flag. - - -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. - - -X: Value in specified commodity - The -X/--exchange=COMM option is like -V, except you tell it which cur- - rency you want to convert to, and it tries to convert everything to - that. - - 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: - - o For single period reports (including normal print and register re- - ports): - - o If an explicit report end date is specified, that is used. - - o Otherwise the latest transaction date or non-future P directive - date is used. - - o 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. - - 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 direc- - tive, 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 com- - bining 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 con- - verted. - - --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 confus- - ing/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: - - o multicommodity transactions with explicit prices (@/@@) - - o multicommodity transactions with implicit prices (no @, two commodi- - ties, unbalanced). (With these, the order of postings matters. - hledger print -x can be useful for troubleshooting.) - - o 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: - - o -X EUR --infer-market-prices, not -V --infer-market-prices - - o --value=then,EUR --infer-market-prices, not --value=then --infer-mar- - ket-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 - - 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 suit- - able 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: - - o If you have P directives, they determine which commodities -V will - convert, and to what. - - o 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 con- - verted. - - --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 commod- - ity, using market prices on each posting's date. - - --value=end - Convert amounts to their value in the default valuation commod- - ity, 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 commod- - ity using current market prices (as of when report is gener- - ated). - - --value=YYYY-MM-DD - Convert amounts to their value in the default valuation commod- - ity 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. - - Valuation examples - Here are some quick examples of -V: - - ; one euro is worth this many dollars from nov 1 - P 2016/11/01 $1.10 - - ; purchase some euros on nov 3 - 2016/11/3 - assets:euros 100 - assets:checking - - ; the euro is worth fewer dollars by dec 21 - P 2016/12/21 $1.03 - - How many euros do I have ? - - $ hledger -f t.j bal -N euros - 100 assets:euros - - What are they worth at end of nov 3 ? - - $ hledger -f t.j bal -N euros -V -e 2016/11/4 - $110.00 assets:euros - - What are they worth after 2016/12/21 ? (no report end date specified, - defaults to today) - - $ hledger -f t.j bal -N euros -V - $103.00 assets:euros - - Here are some examples showing the effect of --value, as seen with - print: - - P 2000-01-01 A 1 B - P 2000-02-01 A 2 B - P 2000-03-01 A 3 B - P 2000-04-01 A 4 B - - 2000-01-01 - (a) 1 A @ 5 B - - 2000-02-01 - (a) 1 A @ 6 B - - 2000-03-01 - (a) 1 A @ 7 B - - Show the cost of each posting: - - $ hledger -f- print --cost - 2000-01-01 - (a) 5 B - - 2000-02-01 - (a) 6 B - - 2000-03-01 - (a) 7 B - - Show the value as of the last day of the report period (2000-02-29): - - $ hledger -f- print --value=end date:2000/01-2000/03 - 2000-01-01 - (a) 2 B - - 2000-02-01 - (a) 2 B - - With no report period specified, the latest transaction date or price - date is used as valuation date (2000-04-01): - - $ hledger -f- print --value=end - 2000-01-01 - (a) 3 B - - 2000-02-01 - (a) 3 B - - 2000-03-01 - (a) 3 B - - The value today is the same (the 2000-04-01 price is still in effect): - - $ 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 - - Interaction of valuation and queries - When matching postings based on queries in the presence of valuation, - the following happens: - - 1. The query is separated into two parts: - - 1. the currency (cur:) or amount (amt:). - - 2. all other parts. - - 2. The postings are matched to the currency and amount queries based on - pre-valued amounts. - - 3. Valuation is applied to the postings. - - 4. The postings are matched to the other parts of the query based on - post-valued amounts. - - Related: #1625 - - Effect of valuation on reports - Here is a reference for how valuation is supposed to affect each part - of hledger's reports. It may be useful when troubleshooting. If you - find problems, please report them, ideally with a reproducible example. - Related: #329, #1083. - - First, a quick glossary: - - cost calculated using price(s) recorded in the transaction(s). - - value market value using available market price declarations, or the - unchanged amount if no conversion rate can be found. - - report start - the first day of the report period specified with -b or -p or - date:, otherwise today. - - report or journal start - the first day of the report period specified with -b or -p or - date:, otherwise the earliest transaction date in the journal, - otherwise today. - - report end - the last day of the report period specified with -e or -p or - date:, otherwise today. - - report or journal end - the last day of the report period specified with -e or -p or - date:, otherwise the latest transaction date in the journal, - otherwise today. - - report interval - a flag (-D/-W/-M/-Q/-Y) or period expression that activates the - report's multi-period mode (whether showing one or many subperi- - ods). - - Report -B, --cost -V, -X --value=then --value=end --value=DATE, - type --value=now - -------------------------------------------------------------------------------------------- - print - posting cost value at re- value at posting value at re- value at - amounts port end or date port or DATE/today - today journal end - balance unchanged unchanged unchanged unchanged unchanged - asser- - tions/as- - signments - - register - starting cost value at re- valued at day value at re- value at - balance port or each historical port or DATE/today - (-H) journal end posting was made journal end - starting cost value at day valued at day value at day value at - balance before re- each historical before re- DATE/today - (-H) with port or posting was made port or - report journal journal - interval start start - posting cost value at re- value at posting value at re- value at - amounts port or date port or DATE/today - journal end journal end - summary summarised value at pe- sum of postings value at pe- value at - posting cost riod ends in interval, val- riod ends DATE/today - amounts ued at interval - with re- start - port in- - terval - running sum/average sum/average sum/average of sum/average sum/average - total/av- of displayed of displayed displayed values of displayed of displayed - erage values values values values - - balance - (bs, bse, - cf, is) - balance sums of value at re- value at posting value at re- value at - changes costs port end or date port or DATE/today of - today of journal end sums of post- - sums of of sums of ings - postings postings - budget like balance like balance like balance like bal- like balance - amounts changes changes changes ances changes - (--bud- - get) - grand to- sum of dis- sum of dis- sum of displayed sum of dis- sum of dis- - tal played val- played val- valued played val- played values - ues ues ues - - balance - (bs, bse, - cf, is) - with re- - port in- - terval - starting sums of value at re- sums of values of value at re- sums of post- - balances costs of port start postings before port start ings before - (-H) postings be- of sums of report start at of sums of report start - fore report all postings respective post- all postings - start before re- ing dates before re- - port start port start - balance sums of same as sums of values of balance value at - changes costs of --value=end postings in pe- change in DATE/today of - (bal, is, postings in riod at respec- each period, sums of post- - bs period tive posting valued at ings - --change, dates period ends - cf - --change) - end bal- sums of same as sums of values of period end value at - ances costs of --value=end postings from be- balances, DATE/today of - (bal -H, postings fore period start valued at sums of post- - is --H, from before to period end at period ends ings - bs, cf) report start respective post- - to period ing dates - end - budget like balance like balance like balance like bal- like balance - amounts changes/end changes/end changes/end bal- ances changes/end - (--bud- balances balances ances balances - get) - row to- sums, aver- sums, aver- sums, averages of sums, aver- sums, aver- - tals, row ages of dis- ages of dis- displayed values ages of dis- ages of dis- - averages played val- played val- played val- played values - (-T, -A) ues ues ues - column sums of dis- sums of dis- sums of displayed sums of dis- sums of dis- - totals played val- played val- values played val- played values - ues ues ues - grand to- sum, average sum, average sum, average of sum, average sum, average - tal, of column of column column totals of column of column to- - grand av- totals totals totals tals - erage - - - --cumulative is omitted to save space, it works like -H but with a zero - starting balance. - -PART 4: COMMANDS - Here are hledger's standard subcommands. You can list these by running - hledger. If you have installed more add-on commands, they also will be - listed. - - In the following command docs, each command's specific options are - shown. Most commands also support the general options described above, - though some of them might have no effect. (Usually if there's a sensi- - ble way for a general option to affect a command, it will.) You can - list all of a command's options by running hledger CMD -h. - - Help commands - - o commands - show the hledger commands list (default) - - o demo - show small hledger demos in the terminal - - o help - show the hledger manual with info, man, or pager - - User interface commands - - o repl - run commands from an interactive prompt - - o run - run commands from a script - - o ui - (if installed) run hledger's terminal UI - - o web - (if installed) run hledger's web UI - - Data entry commands - - o add - add transactions using terminal prompts - - o import - add new transactions from other files, eg CSV files - - Basic report commands - - o accounts - show account names - - o codes - show transaction codes - - o commodities - show commodity/currency symbols - - o descriptions - show transaction descriptions - - o files - show input file paths - - o notes - show note parts of transaction descriptions - - o payees - show payee parts of transaction descriptions - - o prices - show market prices - - o stats - show journal statistics - - o tags - show tag names - - Standard report commands - - o print - show transactions or export journal data - - o aregister (areg) - show transactions in a particular account - - o register (reg) - show postings in one or more accounts & running to- - tal - - o balancesheet (bs) - show assets, liabilities and net worth - - o balancesheetequity (bse) - show assets, liabilities and equity - - o cashflow (cf) - show changes in liquid assets - - o incomestatement (is) - show revenues and expenses - - Advanced report commands - - o balance (bal) - show balance changes, end balances, budgets, gains.. - - o roi - show return on investments - - Chart commands - - o activity - show bar charts of posting counts per period - - Data generation commands - - o close - generate balance-zeroing/restoring transactions - - o rewrite - generate auto postings, like print --auto - - Maintenance commands - - o check - check for various kinds of error in the data - - o diff - compare account transactions in two journal files - - o setup - check and show the status of the hledger installation - - o test - run self tests - - Next, these commands are described in detail. - -Help commands - commands - Show the hledger commands list. - - Flags: - --builtin show only builtin commands, not addons - - demo - Play demos of hledger usage in the terminal, if asciinema is installed. - - Flags: - -s --speed=SPEED playback speed (1 is original speed, .5 is half, 2 - is double, etc (default: 2)) - - Run this command with no argument to list the demos. To play a demo, - write its number or a prefix or substring of its title. Tips: - - Make your terminal window large enough to see the demo clearly. - - Use the -s/--speed SPEED option to set your preferred playback speed, - eg -s4 to play at 4x original speed or -s.5 to play at half speed. The - default speed is 2x. - - During playback, several keys are available: SPACE to pause/unpause, . - to step forward (while paused), CTRL-c quit. - - Examples: - - $ hledger demo # list available demos - $ hledger demo 1 # play the first demo at default speed (2x) - $ hledger demo install -s4 # play the "install" demo at 4x speed - - This command is experimental: there aren't many useful demos yet. - - help - Show the hledger user manual with info, man, or a pager. With a (case - insensitive) TOPIC argument, try to open it at that section heading. - - Flags: - -i show the manual with info - -m show the manual with man - -p show the manual with $PAGER or less - (less is always used if TOPIC is specified) - - This command shows the hledger manual built in to your hledger exe- - cutable. It can be useful when offline, or when you prefer the termi- - nal to a web browser, or when the appropriate hledger manual or viewers - are not installed properly on your system. - - By default it chooses the best viewer found in $PATH, trying in this - order: info, man, $PAGER, less, more, stdout. (If a TOPIC is speci- - fied, $PAGER and more are not tried.) You can force the use of info, - man, or a pager with the -i, -m, or -p flags. If no viewer can be - found, or if running non-interactively, it just prints the manual to - stdout. - - When using info, TOPIC can match either the full heading or a prefix. - If your info --version is < 6, you'll need to upgrade it, eg with 'brew - install texinfo' on mac. - - When using man or less, TOPIC must match the full heading. For a pre- - fix match, you can write 'TOPIC.*'. - - Examples - - $ hledger help -h # show the help command's usage - $ hledger help # show the manual with info, man or $PAGER - $ hledger help 'time periods' # show the manual's "Time periods" topic - $ hledger help 'time periods' -m # use man, even if info is installed - -User interface commands - repl - Start an interactive prompt, where you can run any of hledger's com- - mands. Data files are parsed just once, so the commands run faster. - - Flags: - no command-specific flags - - This command is experimental and could change in the future. - - hledger repl starts a read-eval-print loop (REPL) where you can enter - commands interactively. As with the run command, each input file (or - each input file/input options combination) is parsed just once, so com- - mands will run more quickly than if you ran them individually at the - command line. - - Also like run, the input file(s) specified for the repl command will be - the default input for all interactive commands. You can override this - temporarily by specifying an -f option in particular commands. But - note that commands will not see any changes made to input files (eg by - add) until you exit and restart the REPL. - - The command syntax is the same as with run: - - o enter one hledger command at a time, without the usual hledger first - word - - o empty lines and comment text from # to end of line are ignored - - o use single or double quotes to quote arguments when needed - - o type exit or quit or control-D to exit the REPL. - - While it is running, the REPL remembers your command history, and you - can navigate in the usual ways: - - o Keypad or Emacs navigation keys to edit the current command line - - o UP/DOWN or control-P/control-N to step back/forward through history - - o control-R to search for a past command - - o TAB to complete file paths. - - Generally repl command lines should feel much like the normal hledger - CLI, but you may find differences. repl is a little stricter; eg it - requires full command names or official abbreviations (as seen in the - commands list). - - The commands and help commands, and the command help flags (CMD --tldr, - CMD -h/--help, CMD --info, CMD --man), can be useful. - - You can type control-C to cancel a long-running command (but only once; - typing it a second time will exit the REPL). - - And in most shells you can type control-Z to temporarily exit to the - shell (and then fg to return to the REPL). - - Examples - Start the REPL and enter some commands: - - $ hledger repl - Enter hledger commands. To exit, enter 'quit' or 'exit', or send EOF. - % stats - Main file : .../2025.journal - ... - % stats -f 2024/2024.journal - Main file : .../2024.journal - ... - % stats - Main file : .../2025.journal - ... - - or: - - $ hledger repl -f some.journal - Enter hledger commands. To exit, enter 'quit' or 'exit', or send EOF. - % bs - ... - % print -b 'last week' - ... - % bs -f other.journal - ... - - run - Run a sequence of hledger commands, provided as files or command line - arguments. Data files are parsed just once, so the commands run - faster. - - Flags: - no command-specific flags - - This command is experimental and could change in the future. - - You can use run in three ways: - - o hledger run -- CMD1 -- CMD2 -- CMD3 - read commands from the command - line, separated by -- - - o hledger run SCRIPTFILE1 SCRIPTFILE2 - read commands from one or more - files - - o cat SCRIPTFILE1 | hledger run - read commands from standard input. - - run first loads the input file(s) specified by LEDGER_FILE or by -f op- - tions, in the usual way. Then it runs each command in turn, each using - the same input data. But if you want a particular command to use dif- - ferent input, you can specify an -f option within that command. This - will override (not add to) the default input, just for that command. - - Each input file (more precisely, each combination of input file and in- - put options) is parsed only once. This means that commands will not - see any changes made to these files, until the next run. But the com- - mands will run more quickly than if run individually (typically about - twice as fast). - - Command scripts, whether in a file or written on the command line, have - a simple syntax: - - o each line may contain a single hledger command and its arguments, - without the usual hledger first word - - o empty lines are ignored - - o text from # to end of line is a comment, and ignored - - o you can use single or double quotes to quote arguments when needed, - as on the command line - - o these extra commands are available: echo TEXT prints some text, and - exit or quit ends the run. - - On unix systems you can use #!/usr/bin/env hledger run in the first - line of a command file to make it a runnable script. If that gives an - error, use #!/usr/bin/env -S hledger run. - - It's ok to use the run command recursively within a command script. - - You may find some differences in behaviour between run command lines - and normal hledger command lines. run is a little stricter; eg it re- - quires full command names or official abbreviations (as seen in the - commands list), and command options must be written after the command - name. - - Examples - Run commands from the command line: - - hledger -f some.journal run -- balance assets --depth 2 -- balance liabilities -f /some/other.journal --depth 3 --transpose -- stats - - This would load some.journal, run balance assets --depth 2 on it, then - run balance liabilities --depth 3 --transpose on /some/other.journal, - and finally run stats on some.journal - - Run commands from standard input: - - (echo "files"; echo "stats") | hledger -f some.journal run - - Run commands as a script: - - $ cat report - #!/usr/bin/env -S hledger run -f some.journal - - echo "List of accounts in some.journal" - accounts - - echo "Assets of some.journal" - balance assets --depth 2 - - echo "Liabilities from /some/other.journal" - balance liabilities -f /some/other.journal --depth 3 --transpose - - echo "Commands from another.script, applied to another.journal" - run -f another.journal another.script - - $ chmod +x report - $ ./report - List of accounts in some.journal - ... - - ui - Runs hledger-ui (if installed). - - web - Runs hledger-web (if installed). - -Data entry commands - add - Add new transactions to a journal file, with interactive prompting. - - Flags: - --no-new-accounts don't allow creating new accounts - - Many hledger users edit their journals directly with a text editor, or - generate them from CSV. For more interactive data entry, there is the - add command, which prompts interactively on the console for new trans- - actions, 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: - - o add tries to provide useful defaults, using the most similar (by de- - scription) recent transaction (filtered by the query, if any) as a - template. - - o You can also set the initial defaults with command line arguments. - - o Readline-style edit keys can be used during data entry. - - o The tab key will auto-complete whenever possible - accounts, pay- - ees/descriptions, dates (yesterday, today, tomorrow). If the input - area is empty, it will insert the default value. - - o A parenthesised transaction code may be entered following a date. - - o Comments and tags may be entered following a description or amount. - - o If you make a mistake, enter < at any prompt to go one step backward. - - o Input prompts are displayed in a different colour when the terminal - supports it. - - Notes: - - o If you enter a number with no commodity symbol, and you have declared - a default commodity with a D directive, you might expect add to add - this symbol for you. It does not do this; we assume that if you are - using a D directive you prefer not to see the commodity symbol re- - peated on amounts in the journal. - - o add creates entries in journal format; it won't work with timeclock - or timedot files. - - Examples: - - o Record new transactions, saving to the default journal file: - - hledger add - - o Add transactions to 2024.journal, but also load 2023.journal for com- - pletions: - - hledger add --file 2024.journal --file 2023.journal - - o Provide answers for the first four prompts: - - hledger add today 'best buy' expenses:supplies '$20' - - There is a detailed tutorial at https://hledger.org/add.html. - - add and balance assertions - Since hledger 1.43, whenever you enter a posting amount, add will - re-check all balance assertions in the journal, and if any of them - fail, it will report the problem and ask for the amount again. - - You can also add a new balance assertion, following the amount as in - journal format. - - The new transaction's date, and the new posting's posting date if any - (entered in a comment following the amount), will influence assertion - checking. - - You can use -I/--ignore-assertions to disable assertion checking tem- - porarily. - - add and balance assignments - Balance assignments are not recalculated during a hledger add session. - When add runs, it sees the journal with all balance assignments already - processed and converted to assertions. So if you add a new posting - which is dated earlier than a balance assignment, it will break the as- - sertion and be rejected. You can make it work by using hledger add -I. - - import - Import new transactions from one or more data files to the main jour- - nal. - - Flags: - --catchup just mark all transactions as already imported - --dry-run just show the transactions to be imported - - This command detects new transactions in one or more data files speci- - fied as arguments, and appends them to the main journal. - - You can import from any input file format hledger supports, but - CSV/SSV/TSV files, downloaded from financial institutions, are the most - common import source. - - The import destination is the default journal file, or another speci- - fied in the usual way with $LEDGER_FILE or -f/--file. It should be in - journal format. - - Examples: - - $ hledger import bank1-checking.csv bank1-savings.csv - - $ hledger import *.csv - - Import dry run - It's useful to preview the import by running first with --dry-run, to - sanity check the range of dates being imported, and to check the effect - of your conversion rules if converting from CSV. Eg: - - $ hledger import bank.csv --dry-run - - The dry run output is valid journal format, so hledger can re-parse it. - If the output is large, you could show just the uncategorised transac- - tions like so: - - $ hledger import --dry-run bank.csv | hledger -f- -I print unknown - - You could also run this repeatedly to see the effect of edits to your - conversion rules: - - $ watchexec -- "hledger import --dry-run bank.csv | hledger -f- -I print unknown" - - Once the conversion and dates look good enough to import to your jour- - nal, perhaps with some manual fixups to follow, you would do the actual - import: - - $ hledger import bank.csv - - Overlap detection - Reading CSV files is built in to hledger, and not specific to import; - so you could also import by doing hledger -f bank.csv print - >>$LEDGER_FILE. - - But import is easier and provides some advantages. The main one is - that it avoids re-importing transactions it has seen on previous runs. - This means you don't have to worry about overlapping data in successive - downloads of your bank CSV; just download and import as often as you - like, and only the new transactions will be imported each time. - - We don't call this "deduplication", as it's generally not possible to - reliably detect duplicates in bank CSV. Instead, import remembers the - latest date processed previously in each CSV file (saving it in a hid- - den file), and skips any records prior to that date. This works well - for most real-world CSV, where: - - 1. the data file name is stable (does not change) across imports - - 2. the item dates are stable across imports - - 3. the order of same-date items is stable across imports - - 4. the newest items have the newest dates - - (Occasional violations of 2-4 are often harmless; you can reduce the - chance of disruption by downloading and importing more often.) - - Overlap detection is automatic, and shouldn't require much attention - from you, except perhaps at first import (see below). But here's how - it works: - - o For each FILE being imported from: - - 1. hledger reads a file named .latest.FILE file in the same direc- - tory, if any. This file contains the latest record date previ- - ously imported from FILE, in YYYY-MM-DD format. If multiple - records with that date were imported, the date is repeated on N - lines. - - 2. hledger reads records from FILE. If a latest date was found in - step 1, any records before that date, and the first N records on - that date, are skipped. - - o After a successful import from all FILEs, without error and without - --dry-run, hledger updates each FILE's .latest.FILE for next time. - - If this goes wrong, it's relatively easy to repair: - - o You'll notice it before import when you preview with import - --dry-run. - - o Or after import when you try to reconcile your hledger account bal- - ances with your bank. - - o hledger print -f FILE.csv will show all recently downloaded transac- - tions. Compare these with your journal. Copy/paste if needed. - - o Update your conversion rules and print again, if needed. - - o You can manually update or remove the .latest file, or use import - --catchup FILE. - - o Download and import more often, eg twice a week, at least while you - are learning. It's easier to review and troubleshoot when there are - fewer transactions. - - First import - The first time you import from a file, when no corresponding .latest - file has been created yet, all of the records will be imported. - - But perhaps you have been entering the data manually, so you know that - all of these transactions are already recorded in the journal. In this - case you can run hledger import --catchup once. This will create a - .latest file containing the latest CSV record date, so that none of - those records will be re-imported. - - Or, if you know that some but not all of the transactions are in the - journal, you can create the .latest file yourself. Eg, let's say you - previously recorded foobank transactions up to 2024-10-31 in the jour- - nal. Then in the directory where you'll be saving foobank.csv, you - would create a .latest.foobank.csv file containing - - 2024-10-31 - - Or if you had three foobank transactions recorded with that date, you - would repeat the date that many times: - - 2024-10-31 - 2024-10-31 - 2024-10-31 - - Then hledger import foobank.csv [--dry-run] will import only the newer - records. - - Importing balance assignments - Journal entries added by import will have all posting amounts made ex- - plicit (like print -x). - - This means that any balance assignments in the imported entries would - need to be evaluated. But this generally isn't possible, as the main - file's account balances are not visible during import. So try to avoid - generating balance assignments with your CSV rules, or importing from a - journal that contains balance assignments. (Balance assignments are - best avoided anyway.) - - But if you must use them, eg because your CSV includes only balances: - you can import with print, which leaves implicit amounts implicit. - (print can also do overlap detection like import, with the --new flag): - - $ hledger print --new -f bank.csv >> $LEDGER_FILE - - (If you think import should preserve implicit balances, please test - that and send a pull request.) - - Import and commodity styles - Amounts in entries added by import will be formatted according to the - journal's canonical commodity styles, as declared by commodity direc- - tives or inferred from the journal's amounts. - - Related: CSV > Amount decimal places. - - Import archiving - When importing from a CSV rules file (hledger import bank.rules), you - can use the archive rule to enable automatic archiving of the data - file. After a successful import, the data file (specified by source) - will be moved to an archive folder (data/, next to the rules file, - auto-created), and renamed similar to the rules file, with a date. - This can be useful for troubleshooting, detecting variations in your - banks' CSV data, regenerating entries with improved rules, etc. - - The archive rule also causes import to handle source glob patterns dif- - ferently: when there are multiple matched files, it will pick the old- - est, not the newest. - - Import special cases - Deduplication - Here are two kinds of "deduplication" which import does not handle (and - should not, because these can happen legitimately in financial data): - - o Two or more of the new CSV records are identical, and generate iden- - tical new journal entries. - - o A new CSV record generates a journal entry identical to one(s) al- - ready in the journal. - - Varying file name - If you have a download whose file name varies, you could rename it to a - fixed name after each download. Or you could use a CSV source rule - with a suitable glob pattern, and import from the .rules file. - - Multiple versions - Say you download bank.csv, import it, but forget to delete it from your - downloads folder. The next time you download it, your web browser will - save it as (eg) bank (2).csv. The source rule's glob patterns are for - just this situation: instead of specifying source bank.csv, specify - source bank*.csv. Then hledger -f bank.rules CMD or hledger import - bank.rules will automatically pick the newest matched file (bank - (2).csv). - - Alternately, what if you download, but forget to import or delete, then - download again ? Now each of bank.csv and bank (2).csv might contain - data that's not in the other, and not in your journal. In this case, - it's best to import each of them in turn, oldest first (otherwise, - overlap detection could cause new records to be skipped). Enabling im- - port archiving ensures this. Then hledger import bank.rules; hledger - import bank.rules will import and archive first bank.csv, then bank - (2).csv. - -Basic report commands - accounts - List the account names used or declared in the journal. - - Flags: - -u --used list accounts used - -d --declared list accounts declared - --undeclared list accounts used but not declared - --unused list accounts declared but not used - --find list the first account matched by the first - argument (a case-insensitive infix regexp) - --types also show account types when known - --positions also show where accounts were declared - --directives show as account directives, for use in journals - -l --flat list/tree mode: show accounts as a flat list - (default) - -t --tree list/tree mode: show accounts as a tree - --drop=N flat mode: omit N leading account name parts - - This command lists account names - all of them by default. or just the - ones which have been used in transactions, or declared with account di- - rectives, or used but not declared, or declared but not used, or just - the first account name matched by a pattern. - - You can add query arguments to select a subset of transactions or ac- - counts. - - 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 ac- - count's declaration, if any, and the account's overall declaration or- - der; these may be useful when troubleshooting account display order. - - With --directives, it shows valid account directives which could be - pasted into a journal file. This is useful together with --undeclared - when updating your account declarations to satisfy hledger check ac- - counts. - - 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 alphanumeri- - cally-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 - - codes - List the codes seen in transactions, in the order parsed. - - Flags: - no command-specific flags - - This command prints the value of each transaction's code field, in the - order transactions were parsed. The transaction code is an optional - value written in parentheses between the date and description, often - used to store a cheque number, order number or similar. - - Transactions aren't required to have a code, and missing or empty codes - will not be shown by default. With the -E/--empty flag, they will be - printed as blank lines. - - You can add a query to select a subset of transactions. - - Examples: - - 2022/1/1 (123) Supermarket - Food $5.00 - Checking - - 2022/1/2 (124) Post Office - Postage $8.32 - Checking - - 2022/1/3 Supermarket - Food $11.23 - Checking - - 2022/1/4 (126) Post Office - Postage $3.21 - Checking - - $ hledger codes - 123 - 124 - 126 - - $ hledger codes -E - 123 - 124 - - 126 - - commodities - List the commodity symbols used or declared in the journal. - - Flags: - --used list commodities used - --declared list commodities declared - --undeclared list commodities used but not declared - --unused list commodities declared but not used - - This command lists commodity symbols/names - all of them by default, or - just the ones which have been used in transactions or P directives, or - declared with commodity directives, or used but not declared, or de- - clared but not used. - - You can add cur: query arguments to further limit the commodities. - - descriptions - List the unique descriptions used in transactions. - - Flags: - no command-specific flags - - This command lists the unique descriptions that appear in transactions, - in alphabetic order. You can add a query to select a subset of trans- - actions. - - Example: - - $ hledger descriptions - Store Name - Gas Station | Petrol - Person A - - files - List all files included in the journal. With a REGEX argument, only - file names matching the regular expression (case sensitive) are shown. - - Flags: - no command-specific flags - - notes - List the unique notes that appear in transactions. - - Flags: - no command-specific flags - - This command lists the unique notes that appear in transactions, in al- - phabetic order. You can add a query to select a subset of transac- - tions. 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 - - payees - List the payee/payer names used or declared in the journal. - - Flags: - --used list payees used - --declared list payees declared - --undeclared list payees used but not declared - --unused list payees declared but not used - - This command lists unique payee/payer names - all of them by default, - or just the ones which have been used in transaction descriptions, or - declared with payee directives, or used but not declared, or declared - but not used. - - The payee/payer name 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 or pay- - ees. - - Example: - - $ hledger payees - Store Name - Gas Station - Person A - - prices - Print the market prices declared with P directives. With --infer-mar- - ket-prices, also show any additional prices inferred from costs. With - --show-reverse, also show additional prices inferred by reversing known - prices. - - Flags: - --show-reverse also show the prices inferred by reversing known - prices - - Price amounts are always displayed with their full precision, except - for reverse prices which are limited to 8 decimal digits. - - Prices can be filtered by a date:, cur: or amt: query. - - Generally if you run this command with --infer-market-prices --show-re- - verse, 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. - - stats - Show journal and performance statistics. - - Flags: - -v --verbose show more detailed output - -o --output-file=FILE write output to FILE. - - The stats command shows summary information for the whole journal, or a - matched part of it. With a reporting interval, it shows a report for - each report period. - - The default output is fairly impersonal, though it reveals the main - file name. With -v/--verbose, more details are shown, like file paths, - included files, and commodity names. - - It also shows some run time statistics: - - o elapsed time - - o throughput: the number of transactions processed per second - - o live: the peak memory in use by the program to do its work - - o alloc: the peak memory allocation from the OS as seen by GHC. Mea- - suring this externally, eg with GNU time, is more accurate; usually - that will be a larger number; sometimes (with swapping?) smaller. - - The stats command's run time is similar to that of a balance report. - - Example: - - $ hledger stats -f examples/1ktxns-1kaccts.journal - Main file : .../1ktxns-1kaccts.journal - Included files : 0 - Txns span : 2000-01-01 to 2002-09-27 (1000 days) - Last txn : 2002-09-26 (7827 days ago) - Txns : 1000 (1.0 per day) - Txns last 30 days : 0 (0.0 per day) - Txns last 7 days : 0 (0.0 per day) - Payees/descriptions : 1000 - Accounts : 1000 (depth 10) - Commodities : 26 - Market prices : 1000 - Runtime stats : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc - - This command supports the -o/--output-file option (but not -O/--out- - put-format). - - tags - List the tag names used or declared in the journal, or their values. - - Flags: - --used list tags used - --declared list tags declared - --undeclared list tags used but not declared - --unused list tags declared but not used - --values list tag values instead of tag names - --parsed show them in the order they were parsed (mostly), - including duplicates - - This command lists tag names - all of them by default, or just the ones - which have been used on transactions/postings/accounts, or declared - with tag directives, or used but not declared, or declared but not - used. - - You can add one TAGREGEX argument, to show only tags whose name is - matched by this case-insensitive, infix-matching regular expression. - - After that, you can add query arguments to filter the transactions, - postings, or accounts providing tags. - - With --values, 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.) - - Remember that accounts also acquire tags from their parents; postings - also acquire tags from their account and transaction; and transactions - also acquire tags from their postings. - -Standard report commands - print - Show full journal entries, representing transactions. - - Flags: - -x --explicit show all amounts explicitly - --invert display all amounts with reversed sign - --location add tags showing file paths and line numbers - -m --match=DESC fuzzy search for one recent transaction with - description closest to DESC - --new show only newer-dated transactions added in each - file since last run - --round=TYPE how much rounding or padding should be done when - displaying amounts ? - none - show original decimal digits, - as in journal (default) - soft - just add or remove decimal zeros - to match precision - hard - round posting amounts to precision - (can unbalance transactions) - all - also round cost amounts to precision - (can unbalance transactions) - --base-url=URLPREFIX in html output, generate links to hledger-web, - with this prefix. (Usually the base url shown by - hledger-web; can also be relative.) - -O --output-format=FMT select the output format. Supported formats: - txt, beancount, csv, tsv, html, fods, json, sql. - -o --output-file=FILE write output to FILE. A file extension matching - one of the above formats selects that format. - - The print command displays full journal entries (transactions) from the - journal file, sorted by date (or with --date2, by secondary date). - - Directives and inter-transaction comments are not shown, currently. - This means the print command is somewhat lossy, and if you are using it - to reformat/regenerate your journal you should take care to also copy - over the directives and inter-transaction comments. - - Eg: - - $ hledger print -f examples/sample.journal date:200806 - 2008/06/01 gift - assets:bank:checking $1 - income:gifts $-1 - - 2008/06/02 save - assets:bank:saving $1 - assets:bank:checking $-1 - - 2008/06/03 * eat & shop - expenses:food $1 - expenses:supplies $1 - assets:cash $-2 - - print explicitness - Normally, whether posting amounts are implicit or explicit is pre- - served. 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 mak- - ing 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 im- - plicit amount) to be split into multiple single-commodity postings, - keeping the output parseable. - - print amount style - Amounts are shown right-aligned within each transaction (but not - aligned across all transactions; you can do that with ledger-mode in - Emacs). - - Amounts will be (mostly) normalised to their commodity display style: - their symbol placement, decimal mark, and digit group marks will be - made consistent. By default, decimal digits are shown as they are - written in the journal. - - With the --round (Added in 1.32) option, print will try increasingly - hard to display decimal digits according to the commodity display - styles: - - o --round=none show amounts with original precisions (default) - - o --round=soft add/remove decimal zeros in amounts (except costs) - - o --round=hard round amounts (except costs), possibly hiding signifi- - cant digits - - o --round=all round all amounts and costs - - soft is good for non-lossy cleanup, formatting amounts more consis- - tently where it's safe to do so. - - hard and all can cause print to show invalid unbalanced journal en- - tries; they may be useful eg for stronger cleanup, with manual fixups - when needed. - - 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: - - o Value reporting affects posting amounts but not balance assertion or - balance assignment amounts, potentially causing those to fail. - - o Auto postings can generate postings with too many missing amounts. - - o Account aliases can generate bad account names. - - print, other features - With -B/--cost, amounts with costs are shown converted to cost. - - With --invert, posting amounts are shown with their sign flipped. It - could be useful if you have accidentally recorded some transactions - with the wrong signs. - - With --new, print shows only transactions it has not seen on a previous - run. This uses the same deduplication system as the import command. - (See import's docs for details.) - - With -m DESC/--match=DESC, print shows one recent transaction whose de- - scription 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. - - With --location, print adds the source file and line number to every - transaction, as a tag. - - print output format - This command also supports the output destination and output format op- - tions The output formats supported are txt, beancount (Added in 1.32), - csv, tsv (Added in 1.32), json and sql. - - The beancount format tries to produce Beancount-compatible output, as - follows: - - o Transaction and postings with unmarked status are converted to - cleared (*) status. - - o Transactions' payee and note are backslash-escaped and dou- - ble-quote-escaped and wrapped in double quotes. - - o Transaction tags are copied to Beancount #tag format. - - o Commodity symbols are converted to upper case, and a small number of - currency symbols like $ are converted to the corresponding currency - names. - - o Account name parts are capitalised and unsupported characters are re- - placed 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 ac- - counts into compliance.) - - o An open directive is generated for each account used, on the earliest - transaction date. - - Some limitations: - - o Balance assertions are removed. - - o Balance assignments become missing amounts. - - o Virtual and balanced virtual postings become regular postings. - - o 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","","","" - - o There is one CSV record per posting, with the parent transaction's - fields repeated. - - o 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.) - - o The amount is separated into "commodity" (the symbol) and "amount" - (numeric quantity) fields. - - o The numeric amount is repeated in either the "credit" or "debit" col- - umn, for convenience. (Those names are not accurate in the account- - ing sense; it just puts negative amounts under credit and zero or - greater amounts under debit.) - - aregister - (areg) - - Show the transactions and running balances in one account, with each - transaction on one line. - - Flags: - --txn-dates filter strictly by transaction date, not posting - date. Warning: this can show a wrong running - balance. - --no-elide don't show only 2 commodities per amount - --cumulative accumulation mode: show running total from report - start date - -H --historical accumulation mode: show historical running - total/balance (includes postings before report - start date) (default) - --invert display all amounts with reversed sign - --heading=YN show heading row above table: yes (default) or no - -w --width=N set output width (default: terminal width). -wN,M - sets description width as well. - --align-all guarantee alignment across all lines (slower) - -O --output-format=FMT select the output format. Supported formats: - txt, html, csv, tsv, json. - -o --output-file=FILE write output to FILE. A file extension matching - one of the above formats selects that format. - - aregister shows the overall transactions affecting a particular account - (and any subaccounts). Each report line represents one transaction in - this account. Transactions before the report start date are included - in the running balance (--historical mode is the default). You can - suppress this behaviour using the --cumulative option. - - This is a more "real world", bank-like view than the register command - (which shows individual postings, possibly from multiple accounts, not - necessarily in historical mode). As a quick rule of thumb: - use areg- - ister 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 ex- - pression 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:check- - ing 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 - historical balance report with similar arguments. - - Any additional arguments form a query which will filter the transac- - tions shown. Note some queries will disturb the running balance, caus- - ing 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: - - o the transaction's date (or the relevant posting's date if different, - see below) - - o the names of all the other account(s) involved in this transaction - (probably abbreviated) - - o the total change to this account's balance from this transaction - - o the account's historical running balance after this transaction. - - Transactions making a net change of zero are not shown by default; add - the -E/--empty flag to show them. - - For performance reasons, column widths are chosen based on the first - 1000 lines; this means unusually wide values in later lines can cause - visual discontinuities as column widths are adjusted. If you want to - ensure perfect alignment, at the cost of more time and memory, use the - --align-all flag. - - By default, aregister shows a heading above the data. However, when - reporting in a language different from English, it is easier to omit - this heading and prepend your own one. For this purpose, use the - --heading=no option. - - This command also supports the output destination and output format op- - tions. The output formats supported are txt, csv, tsv (Added in 1.32), - html, fods (Added in 1.41) and json. - - 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 post- - ings. 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. - - register - (reg) - - Show postings and their running total. - - Flags: - --cumulative accumulation mode: show running total from report - start date (default) - -H --historical accumulation mode: show historical running - total/balance (includes postings before report - start date) - -A --average show running average of posting amounts instead - of total (implies --empty) - -m --match=DESC fuzzy search for one recent posting with - description closest to DESC - -r --related show postings' siblings instead - --invert display all amounts with reversed sign - --sort=FIELDS sort by: date, desc, account, amount, absamount, - or a comma-separated combination of these. For a - descending sort, prefix with -. (Default: date) - -w --width=N set output width (default: terminal width). -wN,M - sets description width as well. - --align-all guarantee alignment across all lines (slower) - --base-url=URLPREFIX in html output, generate links to hledger-web, - with this prefix. (Usually the base url shown by - hledger-web; can also be relative.) - -O --output-format=FMT select the output format. Supported formats: - txt, csv, tsv, html, fods, json. - -o --output-file=FILE write output to FILE. A file extension matching - one of the above formats selects that format. - - The register command displays matched postings, across all accounts, in - date order, with their running total or running historical balance. - (See also the aregister command, which shows matched transactions in a - specific account.) - - register normally shows line per posting, but note that multi-commodity - amounts will occupy multiple lines (one line per commodity). - - It is typically used with a query selecting a particular account, to - see that account's activity: - - $ hledger register checking - 2008/01/01 income assets:bank:checking $1 $1 - 2008/06/01 gift assets:bank:checking $1 $2 - 2008/06/02 save assets:bank:checking $-1 $1 - 2008/12/31 pay off assets:bank:checking $-1 0 - - With --date2, it shows and sorts by secondary date instead. - - For performance reasons, column widths are chosen based on the first - 1000 lines; this means unusually wide values in later lines can cause - visual discontinuities as column widths are adjusted. If you want to - ensure perfect alignment, at the cost of more time and memory, use the - --align-all flag. - - The --historical/-H flag adds the balance from any undisplayed prior - postings to the running total. This is useful when you want to see - only recent activity, with a historically accurate running balance: - - $ hledger register checking -b 2008/6 --historical - 2008/06/01 gift assets:bank:checking $1 $2 - 2008/06/02 save assets:bank:checking $-1 $1 - 2008/12/31 pay off assets:bank:checking $-1 0 - - The --depth option limits the amount of sub-account detail displayed. - - The --average/-A flag shows the running average posting amount instead - of the running total (so, the final number displayed is the average for - the whole report period). This flag implies --empty (see below). It - is affected by --historical. It works best when showing just one ac- - count 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 num- - bers. It's also useful to show postings on the checking account to- - gether with the related account: - - The --sort=FIELDS flag sorts by the fields given, which can be any of - account, amount, absamount, date, or desc/description, optionally sepa- - rated by commas. For example, --sort account,amount will group all - transactions in each account, sorted by transaction amount. Each field - can be negated by a preceding -, so --sort -amount will show transac- - tions ordered from smallest amount to largest amount. - - $ hledger register --related --invert assets:checking - - With a reporting interval, register shows summary postings, one per in- - terval, 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 op- - tion helps with this, causing subaccounts to be aggregated: - - $ hledger register --monthly assets --depth 1 - 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 in- - tervals. 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 post- - ing will be shown and the program exit code will be non-zero. - - Custom register output - register normally uses the full terminal width (or 80 columns if it - can't detect that). You can override this with the --width/-w option. - - The description and account columns normally share the space equally - (about half of (width - 40) each). You can adjust this by adding a de- - scription width as part of --width's argument, comma-separated: --width - W,D . Here's a diagram (won't display correctly in --help): - - <--------------------------------- width (W) ----------------------------------> - date (10) description (D) account (W-41-D) amount (12) balance (12) - DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA - - and some examples: - - $ hledger reg # use terminal width (or 80 on windows) - $ hledger reg -w 100 # use width 100 - $ hledger reg -w 100,40 # set overall width 100, description width 40 - - This command also supports the output destination and output format op- - tions The output formats supported are txt, csv, tsv (Added in 1.32), - and json. - - balancesheet - (bs) - - Show the end balances in asset and liability accounts. Amounts are - shown with normal positive sign, as in conventional financial state- - ments. - - Flags: - --sum calculation mode: show sum of posting amounts - (default) - --valuechange calculation mode: show total change of value of - period-end historical balances (caused by deposits, - withdrawals, market price fluctuations) - --gain calculation mode: show unrealised capital - gain/loss (historical balance value minus cost - basis) - --count calculation mode: show the count of postings - --change accumulation mode: accumulate amounts from column - start to column end (in multicolumn reports) - --cumulative accumulation mode: accumulate amounts from report - start (specified by e.g. -b/--begin) to column end - -H --historical accumulation mode: accumulate amounts from - journal start to column end (includes postings - before report start date) (default) - -l --flat list/tree mode: show accounts as a flat list - (default). Amounts exclude subaccount amounts, - except where the account is depth-clipped. - -t --tree list/tree mode: show accounts as a tree. Amounts - include subaccount amounts. - --drop=N in list mode, omit N leading account name parts - --declared include non-parent declared accounts (best used - with -E) - -A --average show a row average column (in multicolumn - reports) - -T --row-total show a row total column (in multicolumn reports) - --summary-only display only row summaries (e.g. row total, - average) (in multicolumn reports) - -N --no-total omit the final total row - --no-elide in tree mode, don't squash boring parent accounts - --format=FORMATSTR use this custom line format (in simple reports) - -S --sort-amount sort by amount instead of account code/name - -% --percent express values in percentage of each column's - total - --layout=ARG how to show multi-commodity amounts: - 'wide[,WIDTH]': all commodities on one line - 'tall' : each commodity on a new line - 'bare' : bare numbers, symbols in a column - --base-url=URLPREFIX in html output, generate hyperlinks to - hledger-web, with this prefix. (Usually the base - url shown by hledger-web; can also be relative.) - -O --output-format=FMT select the output format. Supported formats: - txt, html, csv, tsv, json. - -o --output-file=FILE write output to FILE. A file extension matching - one of the above formats selects that format. - - This command displays a balance sheet, showing historical ending bal- - ances of asset and liability accounts. (To see equity as well, use the - balancesheetequity command.) - - Accounts declared with the Asset, Cash or Liability type are shown (see - account types). Or if no such accounts are declared, it shows - top-level accounts named asset or liability (case insensitive, plurals - allowed) and their subaccounts. - - Example: - - $ hledger balancesheet - Balance Sheet 2008-12-31 - - || 2008-12-31 - ====================++============ - Assets || - --------------------++------------ - assets:bank:saving || $1 - assets:cash || $-2 - --------------------++------------ - || $-1 - ====================++============ - Liabilities || - --------------------++------------ - liabilities:debts || $-1 - --------------------++------------ - || $-1 - ====================++============ - Net: || 0 - - This command is a higher-level variant of the balance command, and sup- - ports 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 op- - tions The output formats supported are txt, csv, tsv (Added in 1.32), - html, and json. - - balancesheetequity - (bse) - - This command displays a balance sheet, showing historical ending bal- - ances of asset, liability and equity accounts. Amounts are shown with - normal positive sign, as in conventional financial statements. - - Flags: - --sum calculation mode: show sum of posting amounts - (default) - --valuechange calculation mode: show total change of value of - period-end historical balances (caused by deposits, - withdrawals, market price fluctuations) - --gain calculation mode: show unrealised capital - gain/loss (historical balance value minus cost - basis) - --count calculation mode: show the count of postings - --change accumulation mode: accumulate amounts from column - start to column end (in multicolumn reports) - --cumulative accumulation mode: accumulate amounts from report - start (specified by e.g. -b/--begin) to column end - -H --historical accumulation mode: accumulate amounts from - journal start to column end (includes postings - before report start date) (default) - -l --flat list/tree mode: show accounts as a flat list - (default). Amounts exclude subaccount amounts, - except where the account is depth-clipped. - -t --tree list/tree mode: show accounts as a tree. Amounts - include subaccount amounts. - --drop=N in list mode, omit N leading account name parts - --declared include non-parent declared accounts (best used - with -E) - -A --average show a row average column (in multicolumn - reports) - -T --row-total show a row total column (in multicolumn reports) - --summary-only display only row summaries (e.g. row total, - average) (in multicolumn reports) - -N --no-total omit the final total row - --no-elide in tree mode, don't squash boring parent accounts - --format=FORMATSTR use this custom line format (in simple reports) - -S --sort-amount sort by amount instead of account code/name - -% --percent express values in percentage of each column's - total - --layout=ARG how to show multi-commodity amounts: - 'wide[,WIDTH]': all commodities on one line - 'tall' : each commodity on a new line - 'bare' : bare numbers, symbols in a column - --base-url=URLPREFIX in html output, generate hyperlinks to - hledger-web, with this prefix. (Usually the base - url shown by hledger-web; can also be relative.) - -O --output-format=FMT select the output format. Supported formats: - txt, html, csv, tsv, json. - -o --output-file=FILE write output to FILE. A file extension matching - one of the above formats selects that format. - - This report shows accounts declared with the Asset, Cash, Liability or - Equity type (see account types). Or if no such accounts are declared, - it shows top-level accounts named asset, liability or equity (case in- - sensitive, plurals allowed) and their subaccounts. - - Example: - - $ hledger balancesheetequity - Balance Sheet With Equity 2008-12-31 - - || 2008-12-31 - ====================++============ - Assets || - --------------------++------------ - assets:bank:saving || $1 - assets:cash || $-2 - --------------------++------------ - || $-1 - ====================++============ - Liabilities || - --------------------++------------ - liabilities:debts || $-1 - --------------------++------------ - || $-1 - ====================++============ - Equity || - --------------------++------------ - --------------------++------------ - || 0 - ====================++============ - Net: || 0 - - This command is a higher-level variant of the balance command, and sup- - ports many of that command's features, such as multi-period reports. - It is similar to hledger balance -H assets liabilities equity, but with - smarter account detection, and liabilities/equity displayed with their - sign flipped. - - This report is the easiest way to see if the accounting equation (A+L+E - = 0) is satisfied (after you have done a close --retain to merge rev- - enues and expenses with equity, and perhaps added --infer-equity to - balance your commodity conversions). - - This command also supports the output destination and output format op- - tions The output formats supported are txt, csv, tsv, html, and json. - - cashflow - (cf) - - This command displays a (simple) cashflow statement, showing the in- - flows and outflows affecting "cash" (ie, liquid, easily convertible) - assets. Amounts are shown with normal positive sign, as in conven- - tional financial statements. - - Flags: - --sum calculation mode: show sum of posting amounts - (default) - --valuechange calculation mode: show total change of value of - period-end historical balances (caused by deposits, - withdrawals, market price fluctuations) - --gain calculation mode: show unrealised capital - gain/loss (historical balance value minus cost - basis) - --count calculation mode: show the count of postings - --change accumulation mode: accumulate amounts from column - start to column end (in multicolumn reports) - (default) - --cumulative accumulation mode: accumulate amounts from report - start (specified by e.g. -b/--begin) to column end - -H --historical accumulation mode: accumulate amounts from - journal start to column end (includes postings - before report start date) - -l --flat list/tree mode: show accounts as a flat list - (default). Amounts exclude subaccount amounts, - except where the account is depth-clipped. - -t --tree list/tree mode: show accounts as a tree. Amounts - include subaccount amounts. - --drop=N in list mode, omit N leading account name parts - --declared include non-parent declared accounts (best used - with -E) - -A --average show a row average column (in multicolumn - reports) - -T --row-total show a row total column (in multicolumn reports) - --summary-only display only row summaries (e.g. row total, - average) (in multicolumn reports) - -N --no-total omit the final total row - --no-elide in tree mode, don't squash boring parent accounts - --format=FORMATSTR use this custom line format (in simple reports) - -S --sort-amount sort by amount instead of account code/name - -% --percent express values in percentage of each column's - total - --layout=ARG how to show multi-commodity amounts: - 'wide[,WIDTH]': all commodities on one line - 'tall' : each commodity on a new line - 'bare' : bare numbers, symbols in a column - --base-url=URLPREFIX in html output, generate hyperlinks to - hledger-web, with this prefix. (Usually the base - url shown by hledger-web; can also be relative.) - -O --output-format=FMT select the output format. Supported formats: - txt, html, csv, tsv, json. - -o --output-file=FILE write output to FILE. A file extension matching - one of the above formats selects that format. - - This report shows accounts declared with the Cash type (see account - types). Or if no such accounts are declared, it shows accounts - - o under a top-level account named asset (case insensitive, plural al- - lowed) - - o whose name contains some variation of cash, bank, checking or saving. - - More precisely: all accounts matching this case insensitive regular ex- - pression: - - ^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$) - - and their subaccounts. - - An example cashflow report: - - $ hledger cashflow - Cashflow Statement 2008 - - || 2008 - ====================++====== - Cash flows || - --------------------++------ - assets:bank:saving || $1 - assets:cash || $-2 - --------------------++------ - || $-1 - - This command is a higher-level variant of the balance command, and sup- - ports 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 op- - tions The output formats supported are txt, csv, tsv (Added in 1.32), - html, and json. - - incomestatement - (is) - - Show revenue inflows and expense outflows during the report period. - Amounts are shown with normal positive sign, as in conventional finan- - cial statements. - - Flags: - --sum calculation mode: show sum of posting amounts - (default) - --valuechange calculation mode: show total change of value of - period-end historical balances (caused by deposits, - withdrawals, market price fluctuations) - --gain calculation mode: show unrealised capital - gain/loss (historical balance value minus cost - basis) - --count calculation mode: show the count of postings - --change accumulation mode: accumulate amounts from column - start to column end (in multicolumn reports) - (default) - --cumulative accumulation mode: accumulate amounts from report - start (specified by e.g. -b/--begin) to column end - -H --historical accumulation mode: accumulate amounts from - journal start to column end (includes postings - before report start date) - -l --flat list/tree mode: show accounts as a flat list - (default). Amounts exclude subaccount amounts, - except where the account is depth-clipped. - -t --tree list/tree mode: show accounts as a tree. Amounts - include subaccount amounts. - --drop=N in list mode, omit N leading account name parts - --declared include non-parent declared accounts (best used - with -E) - -A --average show a row average column (in multicolumn - reports) - -T --row-total show a row total column (in multicolumn reports) - --summary-only display only row summaries (e.g. row total, - average) (in multicolumn reports) - -N --no-total omit the final total row - --no-elide in tree mode, don't squash boring parent accounts - --format=FORMATSTR use this custom line format (in simple reports) - -S --sort-amount sort by amount instead of account code/name - -% --percent express values in percentage of each column's - total - --layout=ARG how to show multi-commodity amounts: - 'wide[,WIDTH]': all commodities on one line - 'tall' : each commodity on a new line - 'bare' : bare numbers, symbols in a column - --base-url=URLPREFIX in html output, generate hyperlinks to - hledger-web, with this prefix. (Usually the base - url shown by hledger-web; can also be relative.) - -O --output-format=FMT select the output format. Supported formats: - txt, html, csv, tsv, json. - -o --output-file=FILE write output to FILE. A file extension matching - one of the above formats selects that format. - - This command displays an income statement, showing revenues and ex- - penses during one or more periods. - - It shows accounts declared with the Revenue or Expense type (see ac- - count types). Or if no such accounts are declared, it shows top-level - accounts named revenue or income or expense (case insensitive, plurals - allowed) and their subaccounts. - - Example: - - $ hledger incomestatement - Income Statement 2008 - - || 2008 - ===================++====== - Revenues || - -------------------++------ - income:gifts || $1 - income:salary || $1 - -------------------++------ - || $2 - ===================++====== - Expenses || - -------------------++------ - expenses:food || $1 - expenses:supplies || $1 - -------------------++------ - || $2 - ===================++====== - Net: || 0 - - This command is a higher-level variant of the balance command, and sup- - ports 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 op- - tions The output formats supported are txt, csv, tsv (Added in 1.32), - html, and json. - -Advanced report commands - balance - (bal) - - A flexible, general purpose "summing" report that shows accounts with - some kind of numeric data. This can be balance changes per period, end - balances, budget performance, unrealised capital gains, etc. - - Flags: - --sum calculation mode: show sum of posting amounts - (default) - --valuechange calculation mode: show total change of value of - period-end historical balances (caused by deposits, - withdrawals, market price fluctuations) - --gain calculation mode: show unrealised capital - gain/loss (historical balance value minus cost - basis) - --budget[=DESCPAT] calculation mode: show sum of posting amounts - together with budget goals defined by periodic - transactions. With a DESCPAT argument (must be - separated by = not space), - use only periodic transactions with matching - description - (case insensitive substring match). - --count calculation mode: show the count of postings - --change accumulation mode: accumulate amounts from column - start to column end (in multicolumn reports, - default) - --cumulative accumulation mode: accumulate amounts from report - start (specified by e.g. -b/--begin) to column end - -H --historical accumulation mode: accumulate amounts from - journal start to column end (includes postings - before report start date) - -l --flat list/tree mode: show accounts as a flat list - (default). Amounts exclude subaccount amounts, - except where the account is depth-clipped. - -t --tree list/tree mode: show accounts as a tree. Amounts - include subaccount amounts. - --drop=N in list mode, omit N leading account name parts - --declared include non-parent declared accounts (best used - with -E) - -A --average show a row average column (in multicolumn - reports) - -T --row-total show a row total column (in multicolumn reports) - --summary-only display only row summaries (e.g. row total, - average) (in multicolumn reports) - -N --no-total omit the final total row - --no-elide in tree mode, don't squash boring parent accounts - --format=FORMATSTR use this custom line format (in simple reports) - -S --sort-amount sort by amount instead of account code/name (in - flat mode). With multiple columns, sorts by the row - total, or by row average if that is displayed. - -% --percent express values in percentage of each column's - total - -r --related show the other accounts transacted with, instead - --invert display all amounts with reversed sign - --transpose switch rows and columns (use vertical time axis) - --layout=ARG how to lay out multi-commodity amounts and the - overall table: - 'wide[,W]': commodities on same line, up to W wide - 'tall' : commodities on separate lines - 'bare' : commodity symbols in a separate column - 'tidy' : each data field in its own column - --base-url=URLPREFIX in html output, generate links to hledger-web, - with this prefix. (Usually the base url shown by - hledger-web; can also be relative.) - -O --output-format=FMT select the output format. Supported formats: - txt, html, csv, tsv, json, fods. - -o --output-file=FILE write output to FILE. A file extension matching - one of the above formats selects that format. - - balance is one of hledger's oldest and most versatile commands, for - listing account balances, balance changes, values, value changes and - more, during one time period or many. Generally it shows a table, with - rows representing accounts, and columns representing periods. - - Note there are some variants of the balance command with convenient de- - faults, which are simpler to use: balancesheet, balancesheetequity, - cashflow and incomestatement. When you need more control, then use - balance. - - 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 - other balance-like commands as well (bs, cf, is..). - - balance can show.. - - o accounts as a list (-l) or a tree (-t) - - o optionally depth-limited (-[1-9]) - - o sorted by declaration order and name, or by amount - - ..and their.. - - o balance changes (the default) - - o or actual and planned balance changes (--budget) - - o or value of balance changes (-V) - - o or change of balance values (--valuechange) - - o or unrealised capital gain/loss (--gain) - - o or balance changes from sibling postings (--related/-r) - - o or postings count (--count) - - ..in.. - - o one time period (the whole journal period by default) - - o or multiple periods (-D, -W, -M, -Q, -Y, -p INTERVAL) - - ..either.. - - o per period (the default) - - o or accumulated since report start date (--cumulative) - - o or accumulated since account creation (--historical/-H) - - ..possibly converted to.. - - o cost (--value=cost[,COMM]/--cost/-B) - - o or market value, as of transaction dates (--value=then[,COMM]) - - o or at period ends (--value=end[,COMM]) - - o or now (--value=now) - - o or at some other date (--value=YYYY-MM-DD) - - ..with.. - - o totals (-T), averages (-A), percentages (-%), inverted sign (--in- - vert) - - o rows and columns swapped (--transpose) - - o another field used as account name (--pivot) - - o custom-formatted line items (single-period reports only) (--format) - - o commodities displayed on the same line or multiple lines (--layout) - - This command supports the output destination and output format options, - with output formats txt, csv, tsv (Added in 1.32), json, and (multi-pe- - riod reports only:) html, fods (Added in 1.40). In txt output in a - colour-supporting terminal, negative amounts are shown in red. - - Simple balance report - 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 bal- - ance at the end of the journal period; more on this below. - - Accounts are sorted by declaration order if any, and then alphabeti- - cally 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 (re- - vealing 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. - - 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 ac- - count/balance pair. It may contain any suitable text, with data fields - interpolated like so: - - %[MIN][.MAX](FIELDNAME) - - o MIN pads with spaces to at least this width (optional) - - o MAX truncates at this width (optional) - - o FIELDNAME must be enclosed in parentheses, and can be one of: - - o depth_spacer - a number of spaces equal to the account's depth, or - if MIN is specified, MIN * depth spaces. - - o account - the account's name - - o total - the account's balance/posted total, right justified - - Also, FMT can begin with an optional prefix to control how multi-com- - modity amounts are rendered: - - o %_ - render on multiple lines, bottom-aligned (the default) - - o %^ - render on multiple lines, top-aligned - - o %, - render on one line, comma-separated - - There are some quirks. Eg in one-line mode, %(depth_spacer) has no ef- - fect, instead %(account) has indentation built in. Experimentation - may be needed to get pleasing results. - - Some example formats: - - o %(total) - the account's total - - o %-20.20(account) - the account's name, left justified, padded to 20 - characters and clipped at 20 characters - - o %,%-50(account) %25(total) - account name padded to 50 characters, - total padded to 20 characters, with multiple commodities rendered on - one line - - o %20(total) %2(depth_spacer)%-(account) - the default format for the - single-column balance report - - 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 - - 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: - - o "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). - - o 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-plaintextac- - counting-users. A tree mode report's final total is the sum of the - top-level balances shown, not of all the balances shown. - - o Each group of sibling accounts (ie, under a common parent) is sorted - separately. - - 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 - - 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 - - Showing declared accounts - With --declared, accounts which have been declared with an account di- - rective 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 re- - port, even when you don't have transactions in all of your declared ac- - counts yet. - - Sorting by amount - With -S/--sort-amount, accounts with the largest (most positive) bal- - ances 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 commod- - ity 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 --in- - vert to flip the signs. Or you could use one of the higher-level bal- - ance reports (bs, is..), which flip the sign automatically (eg: hledger - is -MAS). - - 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 col- - umn 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: - - 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), bal- - ance 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: - - o The report's start/end dates will be expanded, if necessary, to fully - encompass the displayed subperiods (so that the first and last subpe- - riods have the same duration as the others). - - o Leading and trailing periods (columns) containing all zeroes are not - shown, unless -E/--empty is used. - - o Accounts (rows) containing all zeroes are not shown, unless - -E/--empty is used. - - o Amounts with many commodities are shown in abbreviated form, unless - --no-elide is used. - - o Average and/or total columns can be added with the -A/--average and - -T/--row-total flags. - - o The --transpose flag can be used to exchange rows and columns. - - o The --pivot FIELD option causes a different transaction field to be - used as "account name". See PIVOTING. - - o The --summary-only flag (--summary also works) hides all but the To- - tal and Average columns (those should be enabled with --row-total and - -A/--average). - - Multi-period reports with many periods can be too wide for easy viewing - in the terminal. Here are some ways to handle that: - - o Hide the totals row with -N/--no-total - - o Filter to a single currency with cur: - - o Convert to a single currency with -V [--infer-market-price] - - o Use a more compact layout like --layout=bare - - o Maximize the terminal window - - o Reduce the terminal's font size - - o View with a pager like less, eg: hledger bal -D --color=yes | less - -RS - - o 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) - - o Output as HTML and view with a browser: hledger bal -D -o a.html && - open a.html - - Balance change, end balance - It's important to be clear on the meaning of the numbers shown in bal- - ance reports. Here is some terminology we use: - - A balance change is the net amount added to, or removed from, an ac- - count 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 post- - ings.) - - Balance report modes - 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 ex- - perimentation to get familiar with all the report modes. - - There are three important option groups: - - hledger balance [CALCULATIONMODE] [ACCUMULATIONMODE] [VALUATIONMODE] - ... - - Calculation mode - The basic calculation to perform for each table cell. It is one of: - - o --sum : sum the posting amounts (default) - - o --budget : sum the amounts, but also show the budget goal amount (for - each account/period) - - o --valuechange : show the change in period-end historical balance val- - ues (caused by deposits, withdrawals, and/or market price fluctua- - tions) - - o --gain : show the unrealised capital gain/loss, (the current valued - balance minus each amount's original cost) - - o --count : show the count of postings - - Accumulation mode - How amounts should accumulate across a report's subperiods/columns. - Another way to say it: which time period's postings should contribute - to each cell's calculation. It is one of: - - o --change : calculate with postings from column start to column end, - ie "just this column". Typically used to see revenues/expenses. - (default for balance, cashflow, incomestatement) - - o --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. - - o --historical/-H : calculate with postings from journal start to col- - umn end, ie "all postings from before report start date until this - column's end". Typically used to see historical end balances of as- - sets/liabilities/equity. (default for balancesheet, balancesheete- - quity) - - Valuation mode - Which kind of value or cost conversion should be applied, if any, be- - fore displaying the report. See Cost reporting and Value reporting for - more about conversions. - - A valuation (or cost) mode can be selected with the --value option: - - o no conversion : don't convert to cost or value (default) - - o --value=cost[,COMM] : convert amounts to cost (then optionally to - some other commodity) - - o --value=then[,COMM] : convert amounts to market value on transaction - dates - - o --value=end[,COMM] : convert amounts to market value on period end - date(s) - (default with --valuechange, --gain) - - o --value=now[,COMM] : convert amounts to market value on today's date - - o --value=YYYY-MM-DD[,COMM] : convert amounts to market value on an- - other date - - or with the legacy -B/-V/-X options, which are equivalent and easier to - type: - - o -B/--cost : like --value=cost - - o -V/--market : like --value=end - - o -X COMM/--exchange COMM : like --value=end,COMM - - Note that --value can also convert to cost, as a convenience; but actu- - ally --cost and --value are independent options, and could be used to- - gether. - - Combining balance report modes - Most combinations of these modes should produce reasonable reports, but - if you find any that seem wrong or misleading, let us know. The fol- - lowing restrictions are applied: - - o --valuechange implies --value=end - - o --valuechange makes --change the default when used with the bal- - ancesheet/balancesheetequity commands - - o --cumulative or --historical disables --row-total/-T - - For reference, here is what the combinations of accumulation and valua- - tion show: - - Valua- no valuation --value= then --value= end --value= - tion:> YYYY-MM-DD - Accumu- /now - lation:v - ----------------------------------------------------------------------------------- - --change change in period sum of post- period-end DATE-value of - ing-date market value of change change in pe- - values in period in period riod - --cumu- change from re- sum of post- period-end DATE-value of - lative port start to ing-date market value of change change from - period end values from re- from report report start - port start to pe- start to period to period end - riod end end - --his- change from sum of post- period-end DATE-value of - torical journal start to ing-date market value of change change from - /-H period end (his- values from jour- from journal journal start - torical end bal- nal start to pe- start to period to period end - ance) riod end end - - Budget report - The --budget report is like a regular balance report, but with two main - differences: - - o Budget goals and performance percentages are also shown, in brackets - - o Accounts which don't have budget goals are hidden by default. - - This is useful for comparing planned and actual income, expenses, time - usage, etc. - - Periodic transaction rules are used to define budget goals. For exam- - ple, here's a periodic rule defining monthly goals for bus travel and - food expenses: - - ;; Budget - ~ monthly - (expenses:bus) $30 - (expenses:food) $400 - - After recording some actual expenses, - - ;; Two months worth of expenses - 2017-11-01 - income $-1950 - expenses:bus $35 - expenses:food:groceries $310 - expenses:food:dining $42 - expenses:movies $38 - assets:bank:checking - - 2017-12-01 - income $-2100 - expenses:bus $53 - expenses:food:groceries $380 - expenses:food:dining $32 - expenses:gifts $100 - assets:bank:checking - - we can see a budget report like this: - - $ hledger bal -M --budget - Budget performance in 2017-11-01..2017-12-31: - - || Nov Dec - ===============++============================================ - || $-425 $-565 - expenses || $425 [ 99% of $430] $565 [131% of $430] - expenses:bus || $35 [117% of $30] $53 [177% of $30] - expenses:food || $352 [ 88% of $400] $412 [103% of $400] - ---------------++-------------------------------------------- - || 0 [ 0% of $430] 0 [ 0% of $430] - - This is "goal-based budgeting"; you define goals for accounts and peri- - ods, often recurring, and hledger shows performance relative to the - goals. This contrasts with "envelope budgeting", which is more de- - tailed and strict - useful when cash is tight, but also quite a bit - more work. https://plaintextaccounting.org/Budgeting has more on this - topic. - - Using the budget report - Historically this report has been confusing and fragile. hledger's - version should be relatively robust and intuitive, but you may still - find surprises. Here are more notes to help with learning and trou- - bleshooting. - - o In the above example, expenses:bus and expenses:food are shown be- - cause they have budget goals during the report period. - - o Their parent expenses is also shown, with budget goals aggregated - from the children. - - o The subaccounts expenses:food:groceries and expenses:food:dining are - not shown since they have no budget goal of their own, but they con- - tribute to expenses:food's actual amount. - - o Unbudgeted accounts expenses:movies and expenses:gifts are also not - shown, but they contribute to expenses's actual amount. - - o The other unbudgeted accounts income and assets:bank:checking are - grouped as . - - o --depth or depth: can be used to limit report depth in the usual way - (but will not reveal unbudgeted subaccounts). - - o Amounts are always inclusive of subaccounts (even in -l/--list mode). - - o Numbers displayed in a --budget report will not always agree with the - totals, because of hidden unbudgeted accounts; this is normal. - -E/--empty can be used to reveal the hidden accounts. - - o In the periodic rules used for setting budget goals, unbalanced post- - ings are convenient. - - o You can filter budget reports with the usual queries, eg to focus on - particular accounts. It's common to restrict them to just expenses. - (The account is occasionally hard to exclude; this is - because of date surprises, discussed below.) - - o When you have multiple currencies, you may want to convert them to - one (-X COMM --infer-market-prices) and/or show just one at a time - (cur:COMM). If you do need to show multiple currencies at once, - --layout bare can be helpful. - - o You can "roll over" amounts (actual and budgeted) to the next period - with --cumulative. - - See also: https://hledger.org/budgeting.html. - - Budget date surprises - With small data, or when starting out, some of the generated budget - goal transaction dates might fall outside the report periods. Eg with - the following journal and report, the first period appears to have no - expenses:food budget. (Also the account should be ex- - cluded by the expenses query, but isn't.): - - ~ monthly in 2020 - (expenses:food) $500 - - 2020-01-15 - expenses:food $400 - assets:checking - - $ hledger bal --budget expenses - Budget performance in 2020-01-15: - - || 2020-01-15 - ===============++==================== - || $400 - expenses:food || 0 [ 0% of $500] - ---------------++-------------------- - || $400 [80% of $500] - - In this case, the budget goal transactions are generated on first days - of of month (this can be seen with hledger print --forecast tag:gener- - ated expenses). Whereas the report period defaults to just the 15th - day of january (this can be seen from the report table's column head- - ings). - - To fix this kind of thing, be more explicit about the report period - (and/or the periodic rules' dates). In this case, adding -b 2020 does - the trick. - - Selecting budget goals - By default, the budget report uses all available periodic transaction - rules to generate goals. This includes rules with a different report - interval from your report. Eg if you have daily, weekly and monthly - periodic rules, all of these will contribute to the goals in a monthly - budget report. - - You can select a subset of periodic rules by providing an argument to - the --budget flag. --budget=DESCPAT will match all periodic rules - whose description contains DESCPAT, a case-insensitive substring (not a - regular expression or query). This means you can give your periodic - rules descriptions (remember that two spaces are needed between period - expression and description), and then select from multiple budgets de- - fined in your journal. - - Budgeting vs forecasting - --forecast and --budget both use the periodic transaction rules in the - journal to generate temporary transactions for reporting purposes. - However they are separate features - though you can use both at the - same time if you want. Here are some differences between them: - - --forecast --budget - -------------------------------------------------------------------------- - is a general option; it enables fore- is a balance command option; it - casting with all reports selects the balance report's - budget mode - generates visible transactions which generates invisible transactions - appear in reports which produce goal amounts - generates forecast transactions from generates budget goal transac- - after the last regular transaction, to tions throughout the report pe- - the end of the report period; or with riod, optionally restricted by - an argument --forecast=PERIODEXPR gen- periods specified in the peri- - erates them throughout the specified odic transaction rules - period, both optionally restricted by - periods specified in the periodic - transaction rules - uses all periodic rules uses all periodic rules; or with - an argument --budget=DESCPAT - uses just the rules matched by - DESCPAT - - Balance report layout - The --layout option affects how balance and the other balance-like com- - mands show multi-commodity amounts and commodity symbols. It can im- - prove readability, for humans and/or machines (other software). It has - four possible values: - - o --layout=wide[,WIDTH]: commodities are shown on a single line, op- - tionally elided to WIDTH - - o --layout=tall: each commodity is shown on a separate line - - o --layout=bare: commodity symbols are in their own column, amounts are - bare numbers - - o --layout=tidy: data is normalised to easily-consumed "tidy" form, - with one row per data value. (This one is currently supported only - by the balance command.) - - Here are the --layout modes supported by each output format Only CSV - output supports all of them: - - - txt csv html json sql - ------------------------------------- - wide Y Y Y - tall Y Y Y - bare Y Y Y - tidy Y - - Examples: - - Wide layout - With many commodities, reports can be very wide: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++==================================================================================================================================================================================================================== - Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT - ------------------++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- - || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT - - A width limit reduces the width, but some commodities will be hidden: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32 - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++=========================================================================================================================== - Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. - ------------------++--------------------------------------------------------------------------------------------------------------------------- - || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. - - 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 has its own - row, amounts are bare numbers, account names are repeated: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare - Balance changes in 2012-01-01..2014-12-31: - - || Commodity 2012 2013 2014 Total - ==================++============================================= - Assets:US:ETrade || GLD 0 70.00 0 70.00 - Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 - Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 - Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 - Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 - ------------------++--------------------------------------------- - || GLD 0 70.00 0 70.00 - || ITOT 10.00 18.00 -11.00 17.00 - || USD 337.18 -98.12 4881.44 5120.50 - || VEA 12.00 10.00 14.00 36.00 - || VHT 106.00 18.00 170.00 294.00 - - Bare layout also affects CSV output, which is useful for producing data - that is easier to consume, eg for making charts: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare - "account","commodity","balance" - "Assets:US:ETrade","GLD","70.00" - "Assets:US:ETrade","ITOT","17.00" - "Assets:US:ETrade","USD","5120.50" - "Assets:US:ETrade","VEA","36.00" - "Assets:US:ETrade","VHT","294.00" - "Total:","GLD","70.00" - "Total:","ITOT","17.00" - "Total:","USD","5120.50" - "Total:","VEA","36.00" - "Total:","VHT","294.00" - - Bare layout will sometimes display an extra row for the no-symbol com- - modity, because of zero amounts (hledger treats zeroes as commod- - ity-less, usually). This can break hledger-bar confusingly - (workaround: add a cur: query to exclude the no-symbol row). - - Tidy layout - This produces normalised "tidy data" (see - https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html) - where every variable has its own column and each row represents a sin- - gle data point. This is the easiest kind of data for other software to - consume: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy - "account","period","start_date","end_date","commodity","value" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" - - Balance report output - As noted in Output format, if you choose HTML output (by using -O html - or -o somefile.html), you can create a hledger.css file in the same di- - rectory to customise the report's appearance. - - The HTML and FODS output formats can generate hyperlinks to a - hledger-web register view for each account and period. E.g. if your - hledger-web server is reachable at http://localhost:5000 then you might - run the balance command with the extra option --base-url=http://local- - host:5000. You can also produce relative links, like - --base-url="some/path" or --base-url="".) - - Some useful balance reports - Some frequently used balance options/reports are: - - o bal -M revenues expenses - Show revenues/expenses in each month. Also available as the incomes- - tatement command. - - o bal -M -H assets liabilities - Show historical asset/liability balances at each month end. Also - available as the balancesheet command. - - o bal -M -H assets liabilities equity - Show historical asset/liability/equity balances at each month end. - Also available as the balancesheetequity command. - - o bal -M assets not:receivable - Show changes to liquid assets in each month. Also available as the - cashflow command. - - Also: - - o bal -M expenses -2 -SA - Show monthly expenses summarised to depth 2 and sorted by average - amount. - - o bal -M --budget expenses - Show monthly expenses and budget goals. - - o bal -M --valuechange investments - Show monthly change in market value of investment assets. - - o bal investments --valuechange -D date:lastweek amt:'>1000' -STA - [--invert] - Show top gainers [or losers] last week - - roi - Shows the time-weighted (TWR) and money-weighted (IRR) rate of return - on your investments. - - Flags: - --cashflow show all amounts that were used to compute - returns - --investment=QUERY query to select your investment transactions - --profit-loss=QUERY --pnl query to select profit-and-loss or - appreciation/valuation transactions - - At a minimum, you need to supply a query (which could be just an ac- - count 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 re- - quested. 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: - - o Error (NotBracketed): No solution for Internal Rate of Return (IRR). - Possible causes: IRR is huge (>1000000%), balance of investment be- - comes negative at some point in time. - - o Error (SearchFailed): Failed to find solution for Internal Rate of - Return (IRR). Either search does not converge to a solution, or con- - verges too slowly. - - Examples: - - o Using roi to compute total return of investment in stocks: - https://github.com/simonmichael/hledger/blob/master/examples/invest- - ing/roi-unrealised.ledger - - o Cookbook > Return on Investment: https://hledger.org/roi.html - - 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'" - - 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. - - o "Cash flow" is depositing or withdrawing money, buying or selling as- - sets, 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 - - o "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 re- - turn. - - 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 - - IRR and TWR explained - "ROI" stands for "return on investment". Traditionally this was com- - puted as a difference between current value of investment and its ini- - tial value, expressed in percentage of the initial value. - - However, this approach is only practical in simple cases, where invest- - ments receives no in-flows or out-flows of money, and where rate of - growth is fixed over time. For more complex scenarios you need differ- - ent 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 percent- - age 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 "unreal- - ized 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 ac- - count 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 invest- - ment and changes in its value change the value of "investment unit". - Change in "unit price" over the reporting period gives you rate of re- - turn of your investment, and make TWR less sensitive than IRR to the - effects of cash in-flows and out-flows. - - References: - - o Explanation of rate of return - - o Explanation of IRR - - o Explanation of TWR - - o IRR vs TWR - - o Examples of computing IRR and TWR and discussion of the limitations - of both metrics - -Chart commands - activity - Show an ascii barchart of posting counts per interval. - - Flags: - no command-specific flags - - The activity command displays an ascii histogram showing transaction - counts by day, week, month or other reporting interval (by day is the - default). With query arguments, it counts only matched transactions. - - Examples: - - $ hledger activity --quarterly - 2008-01-01 ** - 2008-04-01 ******* - 2008-07-01 - 2008-10-01 ** - -Data generation commands - close - (equity) - - close prints several kinds of "closing" and/or "opening" transactions, - useful in various situations: migrating balances to a new journal file, - retaining earnings into equity, consolidating balances, viewing lot - costs.. Like print, it prints valid journal entries. You can copy - these into your journal file(s) when you are happy with how they look. - - Flags: - --clopen[=TAGVAL] show closing and opening balances transactions, - for AL accounts by default - --close[=TAGVAL] show just a closing balances transaction - --open[=TAGVAL] show just an opening balances transaction - --assert[=TAGVAL] show a balance assertions transaction - --assign[=TAGVAL] show a balance assignments transaction - --retain[=TAGVAL] show a retain earnings transaction, for RX - accounts by default - -x --explicit show all amounts explicitly - --show-costs show amounts with different costs separately - --interleaved show source and destination postings together - --assertion-type=TYPE =, ==, =* or ==* - --close-desc=DESC set closing transaction's description - --close-acct=ACCT set closing transaction's destination account - --open-desc=DESC set opening transaction's description - --open-acct=ACCT set opening transaction's source account - --round=TYPE how much rounding or padding should be done when - displaying amounts ? - none - show original decimal digits, - as in journal (default) - soft - just add or remove decimal zeros - to match precision - hard - round posting amounts to precision - (can unbalance transactions) - all - also round cost amounts to precision - (can unbalance transactions) - - close has six modes, selected by choosing one of the mode flags - (--close is the default). They all do much the same operation, but - with different defaults, useful in different situations. - - close --clopen - This is useful if migrating balances to a new journal file at the start - of a new year. It prints a "closing balances" transaction that zeroes - out account balances (Asset and Liability accounts, by default), and an - opposite "opening balances" transaction that restores them again. Typ- - ically, you would run - - hledger close --clopen -e NEWYEAR >> $LEDGER_FILE - - and then move the opening transaction from the old file to the new file - (and probably also update your LEDGER_FILE environment variable). - - Why might you do this ? If your reports are fast, you may not need it. - But at some point you will probably want to partition your data by - time, for performance or data integrity or regulatory reasons. A new - file or set of files per year is common. Then, having each file/file- - set "bookended" with opening and closing balance transactions will al- - low you to freely pick and choose which files to read - just the cur- - rent year, any past year, any sequence of years, or all of them - while - showing correct account balances in each case. The earliest opening - balances transaction sets correct starting balances, and any later - closing/opening pairs will harmlessly cancel each other out. - - The balances will be transferred to and from equity:opening/closing - balances by default. You can override this by using --close-acct - and/or --open-acct. - - You can select a different set of accounts to close/open by providing - an account query. Eg to add Equity accounts, provide arguments like - assets liabilities equity or type:ALE. When migrating to a new file, - you'll usually want to bring along the AL or ALE accounts, but not the - RX accounts (Revenue, Expense). - - Assertions will be added indicating and checking the new balances of - the closed/opened accounts. - - The generated transactions will have a clopen: tag. If the main jour- - nal's base file name contains a number (eg a year number), the tag's - value will be that base file name with the number incremented. Or you - can choose the tag value yourself, by using --clopen=TAGVAL. - - close --close - This prints just the closing balances transaction of --clopen. It is - the default if you don't specify a mode. - - More customisation options are described below. Among other things, - you can use close --close to generate a transaction moving the balances - from any set of accounts, to a different account. (If you need to move - just a portion of the balance, see hledger-move.) - - close --open - This prints just the opening balances transaction of --clopen. (It is - similar to Ledger's equity command.) - - close --assert - This prints a transaction that asserts the account balances as they are - on the end date (and adds an assert: tag). It could be useful as docu- - mention and to guard against changes. - - close --assign - This prints a transaction that assigns the account balances as they are - on the end date (and adds an "assign:" tag). Unlike balance asser- - tions, assignments will post changes to balances as needed to reach the - specified amounts. - - This is another way to set starting balances when migrating to a new - file, and it will set them correctly even in the presence of earlier - files which do not have a closing balances transaction. However, it - can hide errors, and disturb the accounting equation, so --clopen is - usually recommended. - - close --retain - This is like --close, but it closes Revenue and Expense account bal- - ances by default. They will be transferred to equity:retained earn- - ings, or another account specified with --close-acct. - - Revenues and expenses correspond to changes in equity. They are cate- - gorised separately for reporting purposes, but traditionally at the end - of each accounting period, businesses consolidate them into equity, - This is called "retaining earnings", or "closing the books". - - In personal accounting, there's not much reason to do this, and most - people don't. (One reason to do it is to help the balancesheetequity - report show a zero total, demonstrating that the accounting equation - (A-L=E) is satisfied.) - - close customisation - In all modes, the following things can be overridden: - - o the accounts to be closed/opened, with account query arguments - - o the balancing account, with --close-acct=ACCT and/or --open-acct=ACCT - - o the transaction descriptions, with --close-desc=DESC and - --open-desc=DESC - - o the transaction's tag value, with a --MODE=NEW option argument - - o the closing/opening dates, with -e OPENDATE - - By default, the closing date is yesterday, or the journal's end date, - whichever is later; and the opening date is always one day after the - closing date. You can change these by specifying a report end date; - the closing date will be the last day of the report period. Eg -e 2024 - means "close on 2023-12-31, open on 2024-01-01". - - With --x/--explicit, the balancing amount will be shown explicitly, and - if it involves multiple commodities, a separate posting will be gener- - ated for each of them (similar to print -x). - - With --interleaved, each individual transfer is shown with source and - destination postings next to each other (perhaps useful for trou- - bleshooting). - - With --show-costs, balances' costs are also shown, with different costs - kept separate. This may generate very large journal entries, if you - have many currency conversions or investment transactions. close - --show-costs is currently the best way to view investment lots with - hledger. (To move or dispose of lots, see the more capable - hledger-move script.) - - close and balance assertions - close adds balance assertions verifying that the accounts have been re- - set to zero in a closing transaction or restored to their previous bal- - ances in an opening transaction. These provide useful error checking, - but you can ignore them temporarily with -I, or remove them if you pre- - fer. - - Single-commodity, subaccount-exclusive balance assertions (=) are gen- - erated by default. This can be changed with --assertion-type='==*' - (eg). - - When running close you should probably avoid using -C, -R, status: - (filtering by status or realness) or --auto (generating postings), - since the generated balance assertions would then require these. - - Transactions with multiple dates (eg posting dates) spanning the file - boundary also can disrupt the balance assertions: - - 2023-12-30 a purchase made in december, cleared in january - expenses:food 5 - assets:bank:checking -5 ; date: 2023-01-02 - - To solve this you can transfer the money to and from a temporary ac- - count, splitting the multi-day transaction into two single-day transac- - tions: - - ; 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 - - close examples - Retain earnings - Record 2022's revenues/expenses as retained earnings on 2022-12-31, ap- - pending the generated transaction to the journal: - - $ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal - - After this, to see 2022's revenues and expenses you must exclude the - retain earnings transaction: - - $ hledger -f 2022.journal is not:desc:'retain earnings' - - Migrate balances to a new file - Close assets/liabilities on 2022-12-31 and re-open them on 2023-01-01: - - $ hledger close --clopen -f 2022.journal -p 2022 - # copy/paste the closing transaction to the end of 2022.journal - # copy/paste the opening transaction to the start of 2023.journal - - After this, to see 2022's end-of-year balances you must exclude the - closing balances transaction: - - $ hledger -f 2022.journal bs not:desc:'closing balances' - - For more flexibility, it helps to tag closing and opening transactions - with eg clopen:NEWYEAR, then you can ensure correct balances by exclud- - ing all opening/closing transactions except the first, like so: - - $ hledger bs -Y -f 2021.j -f 2022.j -f 2023.j expr:'tag:clopen=2021 or not tag:clopen' - $ hledger bs -Y -f 2021.j -f 2022.j expr:'tag:clopen=2021 or not tag:clopen' - $ hledger bs -Y -f 2022.j -f 2023.j expr:'tag:clopen=2022 or not tag:clopen' - $ hledger bs -Y -f 2021.j expr:'tag:clopen=2021 or not tag:clopen' - $ hledger bs -Y -f 2022.j expr:'tag:clopen=2022 or not tag:clopen' - $ hledger bs -Y -f 2023.j # unclosed file, no query needed - - More detailed close examples - See examples/multi-year. - - rewrite - Print all transactions, rewriting the postings of matched transactions. - For now the only rewrite available is adding new postings, like print - --auto. - - Flags: - --add-posting='ACCT AMTEXPR' add a posting to ACCT, which may be - parenthesised. AMTEXPR is either a literal - amount, or *N which means the transaction's - first matched amount multiplied by N (a - decimal number). Two spaces separate ACCT - and AMTEXPR. - --diff generate diff suitable as an input for - patch tool - - This is a start at a generic rewriter of transaction entries. It reads - the default journal and prints the transactions, like print, but adds - one or more specified postings to any transactions matching QUERY. The - posting amounts can be fixed, or a multiplier of the existing transac- - tion'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 in- - cludes a commodity name, the new posting amount will be in the new com- - modity; otherwise, it will be in the matched posting amount's commod- - ity. - - Re-write rules in a file - During the run this tool will execute so called "Automated Transac- - tions" 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 trans- - actions 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 post- - ings. - - 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 contain- - ing 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 - - rewrite vs. print --auto - This command predates print --auto, and currently does much the same - thing, but with these differences: - - o with multiple files, rewrite lets rules in any file affect all other - files. print --auto uses standard directive scoping; rules affect - only child files. - - o rewrite's query limits which transactions can be rewritten; all are - printed. print --auto's query limits which transactions are printed. - - o rewrite applies rules specified on command line or in the journal. - print --auto applies rules specified in the journal. - -Maintenance commands - check - Check for various kinds of errors in your data. - - Flags: - no command-specific flags - - hledger provides a number of built-in correctness checks to help vali- - date your data and prevent errors. Some are run automatically, some - when you enable --strict mode; or you can run any of them on demand by - providing them as arguments to the check command. check produces no - output and a zero exit code if all is well. Eg: - - hledger check # run basic checks - hledger check -s # run basic and strict checks - hledger check ordereddates payees # run basic checks and two others - - If you are an Emacs user, you can also configure flycheck-hledger to - run these checks, providing instant feedback as you edit the journal. - - Here are the checks currently available. Generally, they are performed - in the order they are shown here (and only the first failure is re- - ported). - - Basic checks - These important checks are performed by default, by almost all hledger - commands: - - o parseable - data files are in a supported format, with no syntax er- - rors and no invalid include directives. This ensures that all files - exist and are readable. - - o autobalanced - all transactions are balanced, after automatically in- - ferring missing amounts and conversion rates and then converting - amounts to cost. This ensures that each transaction's entry is well - formed. - - o assertions - all balance assertions in the journal are passing. Bal- - ance assertions are a strong defense against errors; they help catch - many problems. If this check gets in your way, you can disable it - with -I/--ignore-assertions. Or you can add that to your config file - to disable it by default (and then use -s/--strict or hledger check - assertions to enable it). - - Strict checks - These additional checks are performed by all commands when the - -s/--strict flag is used (strict mode). They provide extra er- - ror-catching power to keep your data clean and correct. Strict mode - also always enables the assertions check. - - o balanced - like autobalanced, but all conversions between commodities - must use explicit cost notation or equity postings. This prevents - wrong conversions caused by typos. - - o commodities - all commodity symbols used must be declared. This - guards against mistyping or omitting commodity symbols. Declaring - commodities also sets their precision for display and transaction - balancing. - - o accounts - all account names used must be declared. This prevents - the use of mis-spelled or outdated account names. - - Other checks - These are not wanted by everyone, but can be run using the check com- - mand: - - o tags - all tags used must be declared. This prevents mis-spelled tag - names. Note hledger fairly often finds unintended tags in comments. - - o payees - all payees used in transactions must be declared. This will - force you to declare any new payee name before using it. Most people - will probably find this a bit too strict. - - o ordereddates - within each file, transactions must be ordered by - date. This is a simple and effective error catcher. It's not in- - cluded in strict mode, but you can add it by running hledger check -s - ordereddates. If enabled, this check is performed before balance as- - sertions. - - o recentassertions - all accounts with balance assertions must have one - that's within the 7 days before their latest posting. This will en- - courage adding balance assertions for your active asset/liability ac- - counts, which in turn should encourage you to reconcile regularly - with those real world balances - another strong defense against er- - rors. hledger close --assert can help generate assertion entries. - Over time the older assertions become somewhat redundant, and you can - remove them if you like (they don't affect performance much, but they - add some noise to the journal). - - o uniqueleafnames - no two accounts may have the same last account name - part (eg the checking in assets:bank:checking). This ensures each - account can be matched by a unique short name, easier to remember and - to type. - - Custom checks - You can build your own custom checks with add-on command scripts. See - also Cookbook > Scripting. Here are some examples from hledger/bin/: - - o hledger-check-tagfiles - all tag values containing / (a forward - slash) exist as file paths - - o hledger-check-fancyassertions - more complex balance assertions are - passing - - diff - Compares a particular account's transactions in two input files. It - shows any transactions to this account which are in one file but not in - the other. - - Flags: - no command-specific flags - - More precisely: for each posting affecting this account in either file, - this command looks for a corresponding posting in the other file which - posts the same amount to the same account (ignoring date, description, - etc). - - Since it compares postings, not transactions, this also works when mul- - tiple bank transactions have been combined into a single journal entry. - - This command is useful eg if you have downloaded an account's transac- - tions from your bank (eg as CSV data): when hledger and your bank dis- - agree 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: - - setup - Check the status of the hledger installation. - - Flags: - no command-specific flags - - setup tests your hledger installation and prints a list of results, - sometimes with helpful hints. This is a good first command to run af- - ter installing hledger. Also after upgrading, or when something's not - working, or just when you want a reminder of where things are. - - It makes one network request to detect the latest hledger release ver- - sion. It's ok if this fails or times out. It will use ANSI color by - default, unless disabled by NO_COLOR or --color=n. It does not use a - pager or a config file. - - It expects that the hledger version you are running is installed in - your PATH. If not, it will stop until you have done that (to keep - things simple). - - Example: - - $ hledger setup - Checking your hledger setup.. - Legend: good, neutral, unknown, warning - - hledger - * is a released version ? no hledger 1.42.99-gbca4b39c5-20250425, mac-aarch64 - * is up to date ? yes 1.42.99 installed, latest is 1.42.1 - * is a native binary for this machine ? yes aarch64 - * is installed in PATH ? yes /Users/simon/.local/bin/hledger - * has a system text encoding configured ? yes UTF-8, data files should use this encoding - * has a user config file ? (optional) no - * current directory has a local config ? yes /Users/simon/src/hledger/hledger.conf - * the config file is readable ? yes /Users/simon/src/hledger/hledger.conf - - terminal - * the NO_COLOR variable is defined ? no - * --color is configured by config file ? no - * hledger will use color by default ? yes - * the PAGER variable is defined ? yes less - * --pager is configured by config file ? no - * hledger will use a pager when needed ? yes /opt/homebrew/bin/less - * the LESS variable is defined ? yes - * the HLEDGER_LESS variable is defined ? no - * adjusting LESS variable for color etc. ? yes - * --pretty is enabled by config file ? no tables will use ASCII characters - * bash shell completions are installed ? ? - * zsh shell completions are installed ? ? - - journal - * the LEDGER_FILE variable is defined ? yes /Users/simon/finance/2025/2025.journal - * a default journal file is readable ? yes /Users/simon/finance/2025/2025.journal - * it includes additional files ? yes 15 - * all commodities are declared ? yes 10 - * all accounts are declared ? yes 160 - * all accounts have types ? no 14 untyped - * accounts of each type were detected ? yes ALERXCV - * commodities/accounts are checked ? no use -s to check commodities/accounts - * balance assertions are checked ? yes use -I to ignore assertions - - test - Run built-in unit tests. - - Flags: - no command-specific flags - - This command runs the unit tests built in to hledger and hledger-lib, - printing the results on stdout. If any test fails, the exit code will - be non-zero. - - This is mainly used by hledger developers, but you can also use it to - sanity-check the installed hledger executable on your platform. All - tests are expected to pass - if you ever see a failure, please report - as a bug! - - Any arguments before a -- argument will be passed to the tasty test - runner as test-selecting -p patterns, and any arguments after -- will - be passed to tasty unchanged. - - Examples: - - $ hledger test # run all unit tests - $ hledger test balance # run tests with "balance" in their name - $ hledger test -- -h # show tasty's options - -PART 5: COMMON TASKS - Here are some quick examples of how to do some basic tasks with - hledger. - -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. - -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 de- - scribed in OPTIONS, here are some tips that might help: - - o command-specific options must go after the command (it's fine to put - common options there too: hledger CMD OPTS ARGS) - - o you can run addon commands via hledger (hledger ui [ARGS]) or di- - rectly (hledger-ui [ARGS]) - - o enclose "problematic" arguments in single quotes - - o if needed, also add a backslash to hide regular expression metachar- - acters from the shell - - o to see how a misbehaving command line is being parsed, add --debug=2. - -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 () - -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/environ- - ment.plist like - - { - "LEDGER_FILE" : "~/finance/2023.journal" - } - - and then run killall Dock in a terminal window (or restart the ma- - chine). - - 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 per- - sists across a reboot, and if you need to be an Administrator): - - > CD - > MKDIR finance - > SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal" - - When correctly configured, in a new terminal window $env:LEDGER_FILE - will show the file path, and so will hledger files. - -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 re- - cent starting date, like today or the start of the week. You can al- - ways 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 bal- - ances on this date. Here are two ways to do it: - - o 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. - - o 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 - -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 - -Reconciling - Periodically you should reconcile - compare your hledger-reported bal- - ances 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 dis- - crepancies. - - 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 al- - ready-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 check- - ing -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 trans- - action history and running balance from your bank with the one re- - ported by hledger reg checking -C. This will be easier if you gen- - erally record transaction dates quite similar to your bank's clear- - ing dates. - - 3. Repeat for other asset/liability accounts. - - Tip: instead of the register command, use hledger-ui to see a live-up- - dating register while you edit the journal: hledger-ui --watch --regis- - ter 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 com- - mit: - - $ git commit -m 'txns' 2023.journal - -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 **** - -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. - -BUGS - We welcome bug reports in the hledger issue tracker - (https://bugs.hledger.org), or on the hledger chat or mail list - (https://hledger.org/support). - - Some known issues and limitations: - - hledger uses the system's text encoding when reading non-ascii text. - If no system encoding is configured, or if the data's encoding is dif- - ferent, hledger will give an error. (See Text encoding, Troubleshoot- - ing.) - - On Microsoft Windows, depending what kind of terminal window you use, - non-ascii characters, ANSI text formatting, and/or the add command's - TAB key, may not be fully supported. (For best results, try a power- - shell window.) - - When processing large data files, hledger uses more memory than Ledger. - - 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 ~/.lo- - cal/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 - o 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://stackover- - flow.com/a/7411509). On Windows, $env:LEDGER_FILE should show it. - - o 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. - - Text decoding issues: I get errors like "Illegal byte sequence" or "In- - valid or incomplete multibyte or wide character" or "commitAndRelease- - Buffer: invalid argument (invalid character)" - hledger usually needs its input to be decodable with the system lo- - cale's text encoding. See Text encoding and Install: Text encoding. - - 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. - - - -AUTHORS - Simon Michael and contributors. - See http://hledger.org/CREDITS.html - - -COPYRIGHT - Copyright 2007-2023 Simon Michael and contributors. - - -LICENSE - Released under GNU GPL v3 or later. - - -SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), ledger(1) - -hledger-1.50.2 September 2025 HLEDGER(1) + This manual is for hledger's command line interface, version 1.50.3. + It also describes the common options, file formats and concepts used by + all hledger programs. It might accidentally teach you some bookkeep- + ing/accounting as well! You don't need to know everything in here to + use hledger productively, but when you have a question about function- + ality, this doc should answer it. It is detailed, so do skip ahead or + skim when needed. You can read it on hledger.org, or as an info manual + or man page on your system. You can also open a built-in copy, at a + point of interest, by running + hledger --man [CMD], hledger --info [CMD] or hledger help [TOPIC]. + + (And for shorter help, try hledger --tldr [CMD].) + + The main function of the hledger CLI is to read plain text files de- + scribing 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, peo- + ple, etc. You can choose any account names you wish, using : to indi- + cate 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 exten- + sive/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. + +PART 1: USER INTERFACE +Input + hledger reads one or more data files, each time you run it. You can + specify a file with -f, like so + + $ hledger -f FILE [-f FILE2 ...] print + + Files are most often in hledger's journal format, with the .journal + file extension (.hledger or .j also work); these files describe trans- + actions, 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 or- + ganised). So we usually configure a different journal file, by setting + the LEDGER_FILE environment variable, to something like ~/fi- + nance/2023.journal. For more about how to do that on your system, see + Common tasks > Setting LEDGER_FILE. + + Text encoding + hledger expects non-ascii input to be decodable with the system lo- + cale's text encoding. (For CSV/SSV/TSV files, this can be overridden + by the encoding CSV rule.) + + So, trying to read non-ascii files which have the wrong text encoding, + or when no system locale is configured, will fail. To fix this, con- + figure your system locale appropriately, and/or convert the files to + your system's text encoding (using iconv on unix, or powershell or + notepad on Windows). See Install: Text encoding for more tips. + + hledger's output will use the system locale's encoding. + + hledger's docs and example files mostly use UTF-8 encoding. + + Data formats + Usually the data file is in hledger's journal format, but it can be in + any of the supported file formats, which currently are: + + Reader: Reads: Automatically used for + files with extensions: + ----------------------------------------------------------------------------- + journal hledger journal files and some .journal .j .hledger + Ledger journals, for transactions .ledger + timeclock timeclock files, for precise time .timeclock + logging + timedot timedot files, for approximate .timedot + time logging + csv Comma- or other delimiter-sepa- .csv + rated values, for data import + ssv Semicolon separated values .ssv + tsv Tab separated values .tsv + rules CSV/SSV/TSV/other separated val- .rules + ues, alternate way + + These formats are described in more detail below. + + hledger detects the format automatically based on the file extensions + shown above. If it can't recognise the file extension, it assumes + journal format. So for non-journal files, it's important to use a + recognised file extension, so as to either read successfully or to show + relevant error messages. + + You can also force a specific reader/format by prefixing the file path + with the format and a colon. Eg, to read a .dat file containing tab + separated values: + + $ hledger -f tsv:/some/file.dat stats + + Standard input + The file name - means standard input: + + $ cat FILE | hledger -f- print + + If reading non-journal data in this way, you'll need to write the for- + mat as a prefix, like timeclock: here: + + $ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:- + + 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: + + o Balance assertions will not see the effect of transactions in previ- + ous files. (Usually this doesn't matter as each file will set the + corresponding opening balances.) + + o 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. + + Strict mode + hledger checks input files for valid data. By default, the most impor- + tant errors are detected, while still accepting easy journal files + without a lot of declarations: + + o Are the input files parseable, with valid syntax ? + + o Are all transactions balanced ? + + o Do all balance assertions pass ? + + With the -s/--strict flag, additional checks are performed: + + o Are all accounts posted to, declared with an account directive ? + (Account error checking) + + o Are all commodities declared with a commodity directive ? (Commodity + error checking) + + o Are all commodity conversions declared explicitly ? + + You can use the check command to run individual checks - the ones + listed above and some more. + +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 man- + agement. Some often-used commands are add, print, register, bal- + ancesheet and incomestatement. + + To show a summary of commands, run hledger with no arguments. You can + see the same commands summary at the start of PART 4: COMMANDS below. + + To use a particular command, run hledger CMD [CMDOPTS] [CMDARGS], + + o CMD is the full command name, or its standard abbreviation shown in + the commands list, or any unambiguous prefix of the name. + + o CMDOPTS are command-specific options, if any. Command-specific op- + tions must be written after the command name. Eg: hledger print -x. + + o 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 termi- + nal, run hledger CMD -h. Eg: hledger bal -h. + + Add-on commands + In addition to the built-in commands, you can install add-on commands, + which will also appear in hledger's commands list. Some of these can + be installed as separate packages; others can be found in hledger's + bin/ directory, documented at https://hledger.org/scripts.html. + + 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 directly: hledger-ui --watch. + + Or you can run them with hledger, like built-in commands: hledger ui + --watch. In this case hledger's config file will be used, so you can + set custom options for the addon there. (Before hledger 1.50, an -- + argument was needed before addon options, but not any more.) + +Options + Run hledger -h to see general command line help. Options can be writ- + ten either before or after the command name. These options are spe- + cific to the hledger CLI: + + Flags: + --conf=CONFFILE Use extra options defined in this config file. If + not specified, searches upward and in XDG config + dir for hledger.conf (or .hledger.conf in $HOME). + -n --no-conf ignore any config file + + And the following general options are common to most hledger commands: + + General input/data transformation flags: + -f --file=[FMT:]FILE Read data from FILE, or from stdin if FILE is -, + inferring format from extension or a FMT: prefix. + Can be specified more than once. If not specified, + reads from $LEDGER_FILE or $HOME/.hledger.journal. + --rules=RULESFILE Use rules defined in this rules file for + converting subsequent CSV/SSV/TSV files. If not + specified, uses FILE.csv.rules for each FILE.csv. + --alias=A=B|/RGX/=RPL transform account names from A to B, or by + replacing regular expression matches + --auto generate extra postings by applying auto posting + rules ("=") to all transactions + --forecast[=PERIOD] Generate extra transactions from periodic rules + ("~"), from after the latest ordinary transaction + until 6 months from now. Or, during the specified + PERIOD (the equals is required). Auto posting rules + will also be applied to these transactions. In + hledger-ui, also make future-dated transactions + visible at startup. + -I --ignore-assertions don't check balance assertions by default + --txn-balancing=... how to check that transactions are balanced: + 'old': use global display precision + 'exact': use transaction precision (default) + --infer-costs infer conversion equity postings from costs + --infer-equity infer costs from conversion equity postings + --infer-market-prices infer market prices from costs + --pivot=TAGNAME use a different field or tag as account names + -s --strict do extra error checks (and override -I) + --verbose-tags add tags indicating generated/modified data + + General output/reporting flags (supported by some commands): + -b --begin=DATE include postings/transactions on/after this date + -e --end=DATE include postings/transactions before this date + (with a report interval, will be adjusted to + following subperiod end) + -D --daily multiperiod report with 1 day interval + -W --weekly multiperiod report with 1 week interval + -M --monthly multiperiod report with 1 month interval + -Q --quarterly multiperiod report with 1 quarter interval + -Y --yearly multiperiod report with 1 year interval + -p --period=PERIODEXP set begin date, end date, and/or report interval, + with more flexibility + --today=DATE override today's date (affects relative dates) + --date2 match/use secondary dates instead (deprecated) + -U --unmarked include only unmarked postings/transactions + -P --pending include only pending postings/transactions + -C --cleared include only cleared postings/transactions + (-U/-P/-C can be combined) + -R --real include only non-virtual postings + -E --empty Show zero items, which are normally hidden. + In hledger-ui & hledger-web, do the opposite. + --depth=DEPTHEXP if a number (or -NUM): show only top NUM levels + of accounts. If REGEXP=NUM, only apply limiting to + accounts matching the regular expression. + -B --cost show amounts converted to their cost/sale amount + -V --market Show amounts converted to their value at period + end(s) in their default valuation commodity. + Equivalent to --value=end. + -X --exchange=COMM Show amounts converted to their value at period + end(s) in the specified commodity. + Equivalent to --value=end,COMM. + --value=WHEN[,COMM] show amounts converted to their value on the + specified date(s) in their default valuation + commodity or a specified commodity. WHEN can be: + 'then': value on transaction dates + 'end': value at period end(s) + 'now': value today + YYYY-MM-DD: value on given date + -c --commodity-style=S Override a commodity's display style. + Eg: -c '.' or -c '1.000,00 EUR' + --pretty[=YN] Use box-drawing characters in text output? Can be + 'y'/'yes' or 'n'/'no'. + If YN is specified, the equals is required. + + General help flags: + -h --help show command line help + --tldr show command examples with tldr + --info show the manual with info + --man show the manual with man + --version show version information + --debug=[1-9] show this much debug output (default: 1) + --pager=YN use a pager when needed ? y/yes (default) or n/no + --color=YNA --colour use ANSI color ? y/yes, n/no, or auto (default) + + Usually hledger accepts any unambiguous flag prefix, eg you can write + --tl instead of --tldr or --dry instead of --dry-run. + + You can combine short flags which don't take arguments, eg you can + write -MAST instead of -M -A -S -T. Flags requiring an argument can't + be combined in this way (-If FILE won't work). + + If the same option appears more than once in a command line, usually + the last (right-most) wins. Similarly, if mutually exclusive flags are + used together, the right-most wins. (When flags are mutually exclu- + sive, they'll usually have a group prefix in --help.) + + With most commands, arguments are interpreted as a hledger query which + filter the data. Some queries can be expressed either with options or + with arguments. + + Below are more tips for using the command line interface - feel free to + skip these until you need them. + + Special characters + In commands you type at the command line, certain characters have spe- + cial meaning and sometimes need to be "escaped" or "quoted", by prefix- + ing backslashes or enclosing in quotes. + + If you are able to minimise the use of special characters in your data, + you won't have to deal with this as much. For example, you could use + hyphen - or underscore _ instead of spaces in account names, and you + could use the USD currency code instead of the $ currency symbol in + amounts. + + But if you prefer to use spaced account names and $, it's fine. Just + be aware of this topic so you can check this doc when needed. (These + examples are mostly tested on unix; some details might need to be + adapted if you're on Windows.) + + Escaping shell special characters + These are some characters which may have special meaning to your shell + (the program which interprets command lines): + + o SPACE, <, >, (, ), |, \, % + + o $ if followed by a word character + + So for example, to match an account name containing spaces, like + "credit card", don't write: + + $ hledger register credit card + + Instead, enclose the name in single quotes: + + $ hledger register 'credit card' + + On unix or in Windows powershell, if you use double quotes your shell + will silently treat $ as variable interpolation. So you should proba- + bly avoid double quotes, unless you want that behaviour, eg in a + script: + + $ hledger register "assets:$SOMEACCT" + + But in an older Windows CMD.EXE window, you must use double quotes: + + C:\Users\Me> hledger register "credit card" + + On unix or in Windows powershell, as an alternative to quotes you can + write a backslash before each special character: + + $ hledger register credit\ card + + Finally, since hledger's query arguments are regular expressions (de- + scribed below), you could also fill that gap with . which matches any + character: + + $ hledger register credit.card + + Escaping regular expression special characters + Some characters also have special meaning in regular expressions, which + hledger's arguments often are. Those include: + + o ., ^, $, [, ], (, ), |, \ + + To escape one of these, write \ before it. But note this is in addi- + tion to the shell escaping above. So for characters which are special + to both shell and regular expressions, like \ and $, you will sometimes + need two levels of escaping. + + For example, a balance report that uses a cur: query restricting it to + just the $ currency, should be written like this: + + $ hledger balance cur:\\$ + + Explanation: + + 1. Add a backslash \ before the dollar sign $ to protect it from regu- + lar expressions (so it will be matched literally with no special + meaning). + + 2. Add another backslash before that backslash, to protect it from the + shell (so the shell won't consume it). + + 3. $ doesn't need to be protected from the shell in this case, because + it's not followed by a word character; but it would be harmless to + do so. + + But here's another way to write that, which tends to be easier: add + backslashes to escape from regular expressions, then enclose with + quotes to escape from the shell: + + $ hledger balance cur:'\$' + + Escaping in other situations + hledger options and arguments are sometimes used in places other than + the command line, where the escaping/quoting rules are different. For + example, backslash-quoting may not be available. Here's a quick refer- + ence: + + In unix shell Use single quotes and/or backslash (or double quotes + for variable interpolation) + In Windows power- Use single quotes (or double quotes for variable in- + shell terpolation) + In Windows cmd Use double quotes + In hledger-ui's Use single or double quotes + filter prompt + In hledger-web's Use single or double quotes + search form + In an argument Don't use spaces, don't shell-escape, do regex-es- + file cape, write one argument/option per line + In a config file Use single or double quotes, and enclose the whole + argument ('desc:a b' not desc:'a b') + In ghci (the Use double quotes, and enclose the whole argument + Haskell REPL) + + Unicode characters + hledger is expected to handle non-ascii characters correctly: + + o 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.) + + o 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: + + o A system locale must be configured, which can decode the characters + being used. This is essential - see Text encoding and Install: Text + encoding. + + o Your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) + must support unicode. On Windows, you may need to use Windows Termi- + nal. + + o The terminal must be using a font which includes the required unicode + glyphs. + + o The terminal should be configured to display wide characters as dou- + ble width (for report alignment). + + o 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 stan- + dard 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). + + 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-expres- + sions.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 char- + acters 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)$ + + 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 re- + placement string to reference capturing groups in the search regexp. + Otherwise, if you write \1, it will match the digit 1. + + 6. they do not support mode modifiers ((?s)), character classes (\w, + \d), or anything else not mentioned above. + + 7. they may not (I'm guessing not) properly support right-to-left or + bidirectional text. + + Some things to note: + + o In the alias directive and --alias option, regular expressions must + be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, + these are not required. + + o 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:\$. + + o On the command line, some metacharacters like $ have a special mean- + ing to the shell and so must be escaped at least once more. See Spe- + cial characters. + + Argument files + You can save a set of command line options and arguments in a file, and + then use them by writing @FILE.args as a hledger command argument. The + .args file extension is conventional, but not required. In an argument + file, + + o Each line can contain one argument, flag, or option. + + o Blank lines or lines beginning with # are ignored. + + o An option's flag and value should be joined by =. + + o An option value or an argument may contain spaces. Don't use single + or double quotes. + + o And generally, use one less level of quoting/escaping than at the + command line. Eg cur:\$, not cur:\\$ as on the command line. + + For example: + + # cash.args + + assets:cash + assets:charles schwab:sweep + cur:\$ + -c=$1. + + $ hledger bal @cash.args + + Config files + With hledger 1.40+, you can save extra command line options and argu- + ments in a more featureful hledger config file. Here's a small exam- + ple: + + # General options are listed first, and used with hledger commands that support them. + --pretty + + # Options following a `[COMMAND]` heading are used with that hledger command only. + [print] + --explicit --infer-costs + + To use a config file, specify it with the --conf option. Its options + will be inserted near the start of your command line, so you can over- + ride them with command line options if needed. + + Or, you can set up an automatic config file that is used whenever you + run hledger, by creating hledger.conf in the current directory or + above, or .hledger.conf in your home directory (~/.hledger.conf), or + hledger.conf in your XDG config directory (~/.con- + fig/hledger/hledger.conf). + + Here is another example config you could start with: + https://github.com/simonmichael/hledger/blob/master/hledger.conf.sample + + You can put not only options, but also arguments in a config file. If + the first word in a config file's top (general) section does not begin + with a dash (eg: print), it is treated as the command argument (over- + riding any argument on the command line). + + On unix machines, you can add a shebang line at the top of a config + file, set executable permission on the file, and use it like a script. + Eg (the -S is needed on some operating systems): + + #!/usr/bin/env -S hledger --conf + + You can ignore config files by adding the -n/--no-conf flag to the com- + mand line. This is useful when using hledger in scripts, or when trou- + bleshooting. When both --conf and --no-conf options are used, the + right-most wins. + + To inspect the processing of config files, use --debug or --debug=8. + Or, run the setup command, which will display any active config files. + (setup is not affected by config files itself, unlike other commands.) + + Warning! + + There aren't many hledger features that need a warning, but this is + one! + + Automatic config files, while convenient, also make hledger less pre- + dictable and dependable. It's easy to make a config file that changes + a report's behaviour, or breaks your hledger-using scripts/applica- + tions, in ways that will surprise you later. + + If you don't want this, + + 1. Just don't create a hledger.conf file on your machine. + + 2. Also be alert to downloaded directories which may contain a + hledger.conf file. + + 3. Also if you are sharing scripts or examples or support, consider + that others may have a hledger.conf file. + + Conversely, once you decide to use this feature, try to remember: + + 1. Whenever a hledger command does not work as expected, try it again + with -n (--no-conf) to see if a config file was to blame. + + 2. Whenever you call hledger from a script, consider whether that call + should use -n or not. + + 3. Be conservative about what you put in your config file; try to con- + sider the effect on all your reports. + + 4. To troubleshoot the effect of config files, run with --debug or + --debug 8. + + The config file feature was added in hledger 1.40. + + Shell completions + If you use the bash or zsh shells, you can optionally set up con- + text-sensitive autocompletion for hledger command lines. Try pressing + hledger (should list all hledger commands) or hledger + reg acct: (should list your top-level account names). If + completions aren't working, or for more details, see Install > Shell + completions. + +Output + 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 pro- + vide 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) + + Output format + Some commands offer other kinds of output, not just text on the termi- + nal. Here are those commands and the formats currently supported: + + command txt html csv/tsv fods beancount sql json + -------------------------------------------------------------------------------------------- + aregister Y Y Y Y Y + balance Y Y Y Y Y + balancesheet Y Y Y Y Y + balancesheetequity Y Y Y Y Y + cashflow Y Y Y Y Y + incomestatement Y Y Y Y Y + print Y Y Y Y Y Y Y + register Y Y Y Y Y + + You can also see which output formats a command supports by running + hledger CMD -h and looking for the -O/--output-format=FMT option, + + You can select the output format by using that option: + + $ hledger print -O csv # print CSV to standard output + + or by choosing a suitable filename extension with the -o/--out- + put-file=FILE.FMT option: + + $ hledger balancesheet -o foo.csv # write CSV to foo.csv + + The -O option can be combined with -o to override the file extension if + needed: + + $ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt + + Here are some notes about the various output formats. + + Text output + This is the default: human readable, plain text report output, suitable + for viewing with a monospace font in a terminal. If your data contains + unicode or wide characters, you'll need a terminal and font that render + those correctly. (This can be challenging on MS Windows.) + + Some reports (register, aregister) will normally use the full window + width. If this isn't working or you want to override it, you can use + the -w/--width option. + + Balance reports (balance, balancesheet, incomestatement...) use what- + ever width they need. Multi-period multi-currency reports can often be + wider than the window. Besides using a pager, helpful techniques for + this situation include --layout=bare, -X COMM, cur:, --transpose, + --tree, --depth, --drop, switching to html output, etc. + + Box-drawing characters + hledger draws simple table borders by default, to minimise the risk of + display problems caused by a terminal/font not supporting box-drawing + characters. + + But your terminal and font probably do support them, so we recommend + using the --pretty flag to show prettier tables in the terminal. This + is a good flag to add to your hledger config file. + + Colour + hledger tries to automatically detect ANSI colour and text styling sup- + port and use it when appropriate. (Currently, it is used rather mini- + mally: some reports show negative numbers in red, and help output uses + bold text for emphasis.) + + You can override this by setting the NO_COLOR environment variable to + disable it, or by using the --color/--colour option, perhaps in your + config file, with a y/yes or n/no value to force it on or off. + + Paging + In unix-like environments, when displaying large output (in any output + format) in the terminal, hledger tries to use a pager when appropriate. + (You can disable this with the --pager=no option, perhaps in your con- + fig file.) + + The pager shows one page of text at a time, and lets you scroll around + to see more. While it is active, usually SPACE shows the next page, h + shows help, and q quits. The home/end/page up/page down/cursor keys, + and mouse scrolling, may also work. + + hledger will use the pager specified by the PAGER environment variable, + otherwise less if available, otherwise more if available. (With one + exception: hledger help -p TOPIC will always use less, so that it can + scroll to the topic.) + + The pager is expected to display hledger's ANSI colour and text + styling. If you see junk characters, you might need to configure your + pager to handle ANSI codes. Or you could disable colour as described + above. + + If you are using the less pager, hledger automatically appends a number + of options to the LESS variable to enable ANSI colour and a number of + other conveniences. (At the time of writing: --chop-long-lines + --hilite-unread --ignore-case --no-init --quit-at-eof + --quit-if-one-screen --RAW-CONTROL-CHARS --shift=8 + --squeeze-blank-lines --use-backslash ). If these don't work well, you + can set your preferred options in the HLEDGER_LESS variable, which will + be used instead. + + HTML output + HTML output can be styled by an optional hledger.css file in the same + directory. + + HTML output will be a HTML fragment, not a complete HTML document. + Like other hledger output, for non-ascii characters it will use the + system locale's text encoding (see Text encoding). + + CSV / TSV output + In CSV or TSV output, digit group marks (such as thousands separators) + are disabled automatically. + + FODS output + FODS is the OpenDocument Spreadsheet format as plain XML, as accepted + by LibreOffice and OpenOffice. If you use their spreadsheet applica- + tions, this is better than CSV because it works across locales (decimal + point vs. decimal comma, character encoding stored in XML header, thus + no problems with umlauts), it supports fixed header rows and columns, + cell types (string vs. number vs. date), separation of number and + currency (currency is displayed but the cell type is still a number ac- + cessible for computation), styles (bold), borders. Btw. you can still + extract CSV from FODS/ODS using various utilities like libreoffice + --headless or ods2csv. + + Beancount output + This is Beancount's journal format. You can use this to export your + hledger data to Beancount, eg to use the Fava web app. + + hledger will try to adjust your data to suit Beancount, automatically. + Be cautious and check the conversion until you are confident it is + good. If you plan to export to Beancount often, you may want to follow + its conventions, for a cleaner conversion: + + o use Beancount-friendly account names + + o use currency codes instead of currency symbols + + o use cost notation instead of equity conversion postings + + o avoid virtual postings, balance assignments, and secondary dates. + + There is one big adjustment you must handle yourself: for Beancount, + the top level account names must be Assets, Liabilities, Equity, In- + come, and/or Expenses. You can use account aliases to rewrite your ac- + count names temporarily, if needed, as in this hledger2beancount.conf + config file. + + 2024-12-20: Some more things not yet handled for you: + + o P directives are not converted automatically - convert those your- + self. + + o Balance assignments are not converted (Beancount doesn't support + them) - replace those with explicit amounts. + + Beancount account names + Aside from the top-level names, hledger will adjust your account names + to make valid Beancount account names, by capitalising each part, re- + placing spaces with -, replacing other unsupported characters with + C, prepending A to account name parts which don't begin with + a letter or digit, and appending :A to account names which have only + one part. + + Beancount commodity names + hledger will adjust your commodity names to make valid Beancount com- + modity/currency names, which must be 2-24 uppercase letters, digits, or + ', ., _, -, beginning with a letter and ending with a letter or digit. + hledger will convert known currency symbols to ISO 4217 currency codes, + capitalise letters, replace spaces with -, replace other unsupported + characters with C, and prepend or append C if needed. + + Beancount virtual postings + Beancount doesn't allow virtual postings; if you have any, they will be + omitted from beancount output. + + Beancount metadata + hledger tags will be converted to Beancount metadata (except for tags + whose name begins with _). Metadata names will be adjusted to be Bean- + count-compatible: beginning with a lowercase letter, at least two char- + acters long, and with unsupported characters encoded. Metadata values + will use Beancount's string type. + + In hledger, objects can have the same tag repeated with multiple val- + ues. Eg an assets:cash account might have both type:Asset and + type:Cash tags. For Beancount these will be combined into one, with + the values combined, comma separated. Eg: type: "Asset, Cash". + + Beancount costs + Beancount doesn't allow redundant costs and conversion postings as + hledger does. If you have any of these, the conversion postings will + be omitted. Currently we support at most one cost + conversion post- + ings group per transaction. + + Beancount operating currency + Declaring an operating currency (or several) improves Beancount and + Fava reports. Currently hledger will declare each currency used in + cost amounts as an operating currency. If needed, replace these with + your own declaration, like + + option "operating_currency" "USD" + + SQL output + SQL output is expected to work at least with SQLite, MySQL and Post- + gres. + + The SQL statements are expected to be executed in the empty database. + If you already have tables created via SQL output of hledger, you would + probably want to either clear data from these (via delete or truncate + SQL statements) or drop the tables completely before import; otherwise + your postings would be duplicated. + + For SQLite, it is more useful if you modify the generated id field to + be a PRIMARY KEY. Eg: + + $ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ... + + This is not yet much used; feedback is welcome. + + JSON output + Our JSON is rather large and verbose, since it is a faithful represen- + tation of hledger's internal data types. To understand its structure, + read the Haskell type definitions, which are mostly in + https://github.com/simonmichael/hledger/blob/mas- + ter/hledger-lib/Hledger/Data/Types.hs. hledger-web's OpenAPI specifi- + cation may also be relevant. + + hledger stores numbers with sometimes up to 255 significant digits. + This is too many digits for most JSON consumers, so in JSON output we + round numbers to at most 10 decimal places. (We don't limit the number + of integer digits.) If you find this causing problems, please let us + know. Related: #1195 + + This is not yet much used; feedback is welcome. + + 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 (ex- + cept for cost amounts and amounts displayed by the print command, which + are always displayed with all decimal digits). For example, the fol- + lowing will force dollar amounts to be displayed as shown: + + $ hledger print -c '$1.000,0' + + This option can be repeated to set the display style for multiple com- + modities/currencies. Its argument is as described in the commodity di- + rective. + + In some cases hledger will adjust number formatting to improve their + parseability (such as adding trailing decimal marks when needed). + + 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 re- + veal when parts of the code are evaluated. To capture debug output in + a log file instead, you can usually redirect stderr, eg: + + hledger bal --debug=3 2>hledger.log + + (This option doesn't work in a config file yet.) + +Environment + These environment variables affect hledger: + + HLEDGER_LESS If less is your pager, this variable specifies the less + options hledger should use. (Otherwise, LESS + custom options are + used.) + + LEDGER_FILE The default journal file, to be used when no -f/--file op- + tion is provided. For example, it could be ~/finance/main.journal. + This can also be a glob pattern, eg ./2???.journal. (If the glob + matches multiple files, only the alphanumerically first one is used.) + If LEDGER_FILE points to a non-existent file, an error will be raised. + If the value is the empty string, it is ignored. + + If LEDGER_FILE is not set and -f is not provided, the default journal + file is $HOME/.hledger.journal (or if a home directory can't be de- + tected, ./.hledger.journal). + + See also Common tasks > Setting LEDGER_FILE. + + NO_COLOR If this environment variable exists (with any value, including + empty), hledger will not use ANSI color codes in terminal output, un- + less overridden by an explicit --color=y or --colour=y option. + +PART 2: DATA FORMATS +Journal + hledger's usual data source is a plain text file containing journal en- + tries in hledger journal format. If you're looking for a quick refer- + ence, jump ahead to the journal cheatsheet (or use the table of con- + tents at https://hledger.org/hledger.html). + + This file represents an accounting General Journal. The .journal file + extension is most often used, though not strictly required. The jour- + nal file contains a number of transaction entries, each describing a + transfer of money (or any commodity) between two or more named ac- + counts, 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 in- + compatible features, you can keep your hledger journal readable by + Ledger and vice versa. This can useful eg for comparing the behaviour + of one app against the other. + + You can use hledger without learning any more about this file; just use + the add or web or import commands to create and update it. + + Many users, though, edit the journal file with a text editor, and track + changes with a version control system such as git. Editor add-ons such + as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and + hledger-vscode for Visual Studio Code, make this easier, adding colour, + formatting, tab completion, and useful commands. See Editor configura- + tion at hledger.org for the full list. + + A hledger journal file can contain three kinds of thing: comment lines, + transactions, and/or directives (including periodic transaction rules + and auto posting rules). Understanding the journal file format will + also give you a good understanding of hledger's data model. Here's a + quick cheatsheet/overview, followed by detailed descriptions of each + part. + + Journal cheatsheet + # Here is the main syntax of hledger's journal format + # (omitting extra Ledger compatibility syntax). + + ############################################################################### + + # 1. These are comment lines, for notes or temporarily disabling things. + ; They begin with # or ; + + comment + Or, lines can be enclosed within "comment" / "end comment". + This is a block of + commented lines. + end comment + + # Some journal entries can have semicolon comments at end of line ; like this + # Some of them require 2 or more spaces before the semicolon. + + ############################################################################### + + # 2. Directives customise processing or output in some way. + # You don't need any directives to get started. + # But they can add more error checking, or change how things are displayed. + # They begin with a word, letter, or symbol. + # They are most often placed at the top, before transactions. + + account assets ; Declare valid account names and display order. + account assets:savings ; A subaccount. This one represents a bank account. + account assets:checking ; Another. Note, 2+ spaces after the account name. + account assets:receivable ; Accounting type is inferred from english names, + account passifs ; or declared with a "type" tag, type:L + account expenses ; type:X + ; A follow-on comment line, indented. + account expenses:rent ; Expense and revenue categories are also accounts. + ; Subaccounts inherit their parent's type. + + commodity $0.00 ; Declare valid commodities and their display styles. + commodity 1.000,00 EUR + + decimal-mark . ; The decimal mark used in this file (if ambiguous). + + payee Whole Foods ; Declare a valid payee name. + + tag trip ; Declare a valid tag name. + + P 2024-03-01 AAPL $179 ; Declare a market price for AAPL in $ on this date. + + include other.journal ; Include another journal file here. + + # Declare a recurring "periodic transaction", for budget/forecast reports + ~ monthly set budget goals ; <- Note, 2+ spaces before the description. + (expenses:rent) $1000 + (expenses:food) $500 + + # Declare an auto posting rule, to modify existing transactions in reports + = revenues:consulting + liabilities:tax:2024:us *0.25 ; Add a tax liability & expense + expenses:tax:2024:us *-0.25 ; for 25% of the revenue. + + ############################################################################### + + # 3. Transactions are what it's all about. + # They are dated events, usually movements of money between 2 or more accounts. + # They begin with a numeric date. + # Here is their basic shape: + # + # DATE DESCRIPTION ; The transaction's date and optional description. + # ACCOUNT1 AMOUNT ; A posting of an amount to/from this account, indented. + # ACCOUNT2 AMOUNT ; A second posting, balancing the first. + # ... ; More if needed. Amounts must sum to zero. + # ; Note, 2+ spaces between account names and amounts. + + 2024-01-01 opening balances ; At the start, declare pre-existing balances this way. + assets:savings $10000 ; Account names can be anything. lower case is easy to type. + assets:checking $1000 ; assets, liabilities, equity, revenues, expenses are common. + liabilities:credit card $-500 ; liabilities, equity, revenues balances are usually negative. + equity:start ; One amount can be left blank. $-10500 is inferred here. + ; Some of these accounts we didn't declare above, + ; so -s/--strict would complain. + + 2024-01-03 ! (12345) pay rent + ; Additional transaction comment lines, indented. + ; There can be a ! or * after the date meaning "pending" or "cleared". + ; There can be a parenthesised (code) after the date/status. + ; Amounts' sign shows direction of flow. + assets:checking $-500 ; Minus means removed from this account (credit). + expenses:rent $500 ; Plus means added to this account (debit). + + ; Keeping transactions in date order is optional (but helps error checking). + + 2024-01-02 Gringott's Bank | withdrawal ; Description can be PAYEE | NOTE + assets:bank:gold -10 gold + assets:pouch 10 gold + + 2024-01-02 shopping + expenses:clothing 1 gold + expenses:wands 5 gold + assets:pouch -6 gold + + 2024-01-02 receive gift + revenues:gifts -3 "Chocolate Frogs" ; Complex commodity symbols + assets:pouch 3 "Chocolate Frogs" ; must be in double quotes. + + 2024-01-15 buy some shares, in two lots ; Cost can be noted. + assets:investments:2024-01-15 2.0 AAAA @ $1.50 ; @ means per-unit cost + assets:investments:2024-01-15-02 3.0 AAAA @@ $4 ; @@ means total cost + ; ^ Per-lot subaccounts are sometimes useful. + assets:checking $-7 + + 2024-01-15 assert some account balances on this date + ; Balances can be asserted in any transaction, with =, for extra error checking. + ; Assertion txns like this one can be made with hledger close --assert --show-costs + ; + assets:savings $0 = $10000 + assets:checking $0 = $493 + assets:bank:gold 0 gold = -10 gold + assets:pouch 0 gold = 4 gold + assets:pouch 0 "Chocolate Frogs" = 3 "Chocolate Frogs" + assets:investments:2024-01-15 0.0 AAAA = 2.0 AAAA @ $1.50 + assets:investments:2024-01-15-02 0.0 AAAA = 3.0 AAAA @@ $4 + liabilities:credit card $0 = $-500 + + 2024-02-01 note some event, or a transaction not yet fully entered, on this date + ; Postings are not required. + + # Consistent YYYY-MM-DD date format is recommended, + # but you can use . or / and omit leading zeros if you prefer. + 2024.01.01 + 2024/1/1 + + 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 re- + gions beginning with a comment line and ending with an end comment line + (or file end). Here's a suggestion for choosing between them: + + o # for top-level notes + + o ; for commenting out things temporarily + + o 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 com- + ments, and Account comments below. + + 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 sim- + ple date in column 0. This can be followed by any of the following op- + tional fields, separated by spaces: + + o a status character (empty, !, or *) + + o a code (any short number or text, enclosed in parentheses) + + o a description (any remaining text until end of line or a semicolon) + + o a comment (any remaining text following a semicolon until end of + line, and any following indented lines beginning with a semicolon) + + o 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 + + Dates + 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 cur- + rent transaction, the default year set with a Y directive, or the cur- + rent 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.) + + 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 re- + ports, 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. + + Status + Transactions (or individual postings within a transaction) can have a + status mark, which is a single character before the transaction de- + scription (or posting account name), separated from it by a space, in- + dicating one of three statuses: + + mark status + ------------------ + unmarked + ! pending + * cleared + + When reporting, you can filter by status with the -U/--unmarked, + -P/--pending, and -C/--cleared flags (and you can combine these, eg -UP + to match all except cleared things). Or you can use the status:, sta- + tus:!, and status:* queries, or the U, P, C keys in hledger-ui. + + (Note: in Ledger the "unmarked" state is called "uncleared"; in hledger + we renamed it to "unmarked" for semantic clarity.) + + Status marks are optional, but can be helpful eg for reconciling with + real-world accounts. Some editor modes provide highlighting and short- + cuts 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 reconcil- + iation) + cleared complete, reconciled as far as possible, and considered cor- + rect + + 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 un- + cashed checks), and no flags to see the most up-to-date state of your + finances. + + 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. + + Description + After the date, status mark and/or code fields, the rest of the line + (or until a comment is begun with ;) is the transaction's description. + Here you can describe the transaction (called the "narration" in tradi- + tional bookkeeping), or you can record a payee/payer name, or you can + leave it empty. + + Transaction descriptions show up in print output and in register re- + ports, and can be listed with the descriptions command. + + You can query by description with desc:DESCREGEX, or pivot on descrip- + tion with --pivot desc. + + Payee and note + Sometimes people want a dedicated payee/payer field that can be queried + and checked more strictly. If you want that, you can write a | (pipe) + character in the description. This divides it into a "payee" field on + the left, and a "note" field on the right. (Either can be empty.) + + You can query these with payee:PAYEEREGEX and note:NOTEREGEX, list + their values with the payees and notes commands, or pivot on payee or + note. + + Note: in transactions with no | character, description, payee, and note + all have the same value. Once a | is added, they become distinct. (If + you'd like to change this behaviour, please propose it on the mail + list.) + + If you want more strict error checking, you can declare the valid payee + names with payee directives, and then enforce these with hledger check + payees. (Note: because of the above, for this you'll need to ensure + every transaction description contains a | and therefore a checkable + payee name, even if it's empty.) + + 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 + + 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: + + o (optional) a status character (empty, !, or *), followed by a space + + o (required) an account name (any text, optionally containing single + spaces, until end of line or a double space) + + o (optional) two or more spaces (or tabs) followed by an amount. + + If the amount is positive, it is being added to the account; if nega- + tive, it is being removed from the account. + + The posting amounts in a transaction must sum up to zero, indicating + that the inflows and outflows are equal. We call this a balanced + transaction. (You can read more about the nitty-gritty details of "sum + up to zero" in Transaction balancing below.) + + As a convenience, you can optionally leave one amount blank; hledger + will infer what it should be so as to balance the transaction. + + Debits and credits + The traditional accounting concepts of debit and credit of course exist + in hledger, but we represent them with numeric sign, as described + above. Positive and negative posting amounts represent debits and + credits respectively. + + You don't need to remember that, but if you would like to - eg for + helping newcomers or for talking with your accountant - here's a handy + mnemonic: + + debit / plus / left / short words + credit / minus / right / longer words + + The two space delimiter + Be sure to notice the unusual separator between the account name and + the following amount. Because hledger allows account names with spaces + in them, you must separate the account name and amount (if any) by two + or more spaces (or tabs). It's easy to forget at first. If you ever + see the amount being treated as part of the account name, you'll know + you probably need to add another space between them. + + 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, liabil- + ities, 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, num- + bers, 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 vir- + tual 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. + + Amounts + After the account name, there is usually an amount. (Remember: between + account name and amount, there must be two or more spaces.) + + hledger's amount format is flexible, supporting several international + formats. Here are some examples. Amounts have a number (the "quan- + tity"): + + 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 com- + modity 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 + + Decimal marks + A decimal mark can be written as a period or a comma: + + 1.23 + 1,23 + + Both of these are common in international number formats, so hledger is + not biased towards one or the other. Because hledger also supports + digit group marks (eg thousands separators), this means that a number + like 1,000 or 1.000 containing just one period or comma is ambiguous. + In such cases, hledger by default assumes it is a decimal mark, and + will parse both of those as 1. + + To help hledger parse such ambiguous numbers more accurately, if you + use digit group marks, we recommend declaring the decimal mark explic- + itly. The best way is to add a decimal-mark directive at the top of + each data file, like this: + + decimal-mark . + + Or you can declare it per commodity with commodity directives, de- + scribed below. + + hledger also accepts numbers like 10. with no digits after the decimal + mark (and will sometimes display numbers that way to disambiguate them + - see Trailing decimal marks). + + Digit group marks + In the integer part of the amount quantity (left of the decimal mark), + groups of digits can optionally be separated by a digit group mark - a + comma or period (whichever is not used as decimal mark), or a space + (several Unicode space variants, like no-break space, are also ac- + cepted). So these are all valid amounts in a journal file: + + $1,000,000.00 + EUR 2.000.000,00 + INR 9,99,99,999.00 + 1 000 000.00 ; <- ordinary space + 1 000 000.00 ; <- no-break space + + 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 punctu- + ation), you must always write it inside double quotes ("green apples", + "ABC123"). + + If you write just a bare number, that too will have a commodity, with + name ""; we call that the "no-symbol commodity". + + Actually, hledger combines these single-commodity amounts into more + powerful multi-commodity amounts, which are what it works with most of + the time. A multi-commodity amount could be, eg: 1 USD, 2 EUR, 3.456 + TSLA. In practice, you will only see multi-commodity amounts in + hledger's output; you can't write them directly in the journal file. + + By default, the format of amounts in the journal influences how hledger + displays them in output. This is explained in Commodity display style + below. + + Costs + After a posting amount, you can note its cost (when buying) or selling + price (when selling) in another commodity, by writing either @ UNIT- + PRICE or @@ TOTALPRICE after it. This indicates a conversion transac- + tion, 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 in- + ferred 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 im- + plicitly: + + 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. + + 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 pro- + tect 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). + + Assertions and ordering + hledger calculates and checks an account's balance assertions in date + order (and when there are multiple assertions on the same day, in parse + order). Note this is different from Ledger, which checks assertions + always in parse order, ignoring dates. + + This means in hledger you can freely reorder transactions, postings, or + files, and balance assertions will usually keep working. The exception + is when you reorder multiple postings on the same day, to the same ac- + count, which have balance assertions; those will likely need updating. + + Assertions and multiple files + If an account has transactions appearing in multiple files, balance as- + sertions can still work - but only if those files are part of a hierar- + chy made by include directives. + + If the same files are specified with two -f options on the command + line, the assertions in the second will not see the balances from the + first. + + To work around this, arrange your files in a hierarchy with include. + Or, you could concatenate the files temporarily, and process them like + one big file. + + Why does it work this way ? It might be related to hledger's goal of + stable predictable reports. File hierarchy is considered "permanent", + part of your data, while the order of command line options/arguments is + not. We don't want transient changes to be able to change the meaning + of the data. Eg it would be frustrating if tomorrow all your balance + assertions broke because you wrote command line arguments in a differ- + ent order. (Discussion welcome.) + + Assertions and costs + Balance assertions ignore costs, and should normally be written without + one: + + 2019/1/1 + (a) $1 @ 1 = $1 + + We do allow costs to be written in balance assertion amounts, however, + and print shows them, but they don't affect whether the assertion + passes or fails. This is for backward compatibility (hledger's close + command used to generate balance assertions with costs), and because + balance assignments do use costs (see below). + + Assertions and commodities + The balance assertions described so far are "single commodity balance + assertions": they assert and check the balance in one commodity, ignor- + ing any others that may be present. This is how balance assertions + work in Ledger also. + + If an account contains multiple commodities, you can assert their bal- + ances by writing multiple postings with balance assertions, one for + each commodity: + + 2013/1/1 + usd $-1 + eur -1 + both + + 2013/1/2 + both 0 = $1 + both 0 = 1 + + In hledger you can make a stronger "sole commodity balance assertion" + by writing two equals signs (== EXPECTEDBALANCE). This also asserts + that there are no other commodities in the account besides the asserted + one (or at least, that their current balance is zero): + + 2013/1/1 + usd $-1 == $-1 ; these sole commodity assertions succeed + eur -1 == -1 + both ;== $1 ; this one would fail because 'both' contains $ and + + It's less easy to make a "sole commodities balance assertion" (note the + plural) - ie, asserting that an account contains two or more specified + commodities and no others. It can be done by + + 1. isolating each commodity in a subaccount, and asserting those + + 2. and also asserting there are no commodities in the parent account + itself: + + 2013/1/1 + usd $-1 + eur -1 + both 0 == 0 ; nothing up my sleeve + both:usd $1 == $1 ; a dollar here + both:eur 1 == 1 ; a euro there + + Assertions and subaccounts + All of the balance assertions above (both = and ==) are "subaccount-ex- + clusive balance assertions"; they ignore any balances that exist in + deeper subaccounts. + + In hledger you can make "subaccount-inclusive balance assertions" by + adding a star after the equals (=* or ==*): + + 2019/1/1 + equity:start + assets:checking $10 + assets:savings $10 + assets $0 ==* $20 ; assets + subaccounts contains $20 and nothing else + + Assertions and status + Balance assertions always consider postings of all statuses (unmarked, + pending, or cleared); they are not affected by the -U/--unmarked / + -P/--pending / -C/--cleared flags or the status: query. + + 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. + + 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: + + o assert the balance calculated with --auto, and always use --auto with + that file + + o or assert the balance calculated without --auto, and never use --auto + with that file + + o or avoid balance assertions on accounts affected by auto postings (or + avoid auto postings entirely). + + 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 asser- + tions. Balance assertion failure messages show exact amounts. + + Assertions and hledger add + Balance assertions can be included in the amounts given in add. All + types of assertions are supported, and assertions can be used as in a + normal journal file. + + All transactions, not just those that have an explicit assertion, are + validated against the existing assertions in the journal. This means + it is possible for an added transaction to fail even if its assertions + are correct as of the transaction date. + + If this assertion checking is not desired, then it can be disabled with + -I. + + However, balance assignments are currently not supported. + + 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 + + Transaction balancing + How exactly does hledger decide when a transaction is balanced ? Espe- + cially when it involves costs, which often are not exact, because of + repeating decimals, or imperfect data from financial institutions ? In + each commodity, hledger sums the transaction's posting amounts, after + converting any with costs; then it checks if that sum is zero, when + rounded to a suitable number of decimal digits - which we call the bal- + ancing precision. + + Since version 1.50, hledger infers balancing precision in each transac- + tion from the amounts in that transaction's journal entry (like + Ledger). Ie, when checking the balance of commodity A, it uses the + highest decimal precision seen for A in the journal entry (excluding + cost amounts). This makes transaction balancing robust; any imbalances + must be visibly accounted for in the journal entry, display precision + can be freely increased with -c, and compatibility with Ledger and + Beancount journals is good. + + Note that hledger versions before 1.50 worked differently: they allowed + display precision to override the balancing precision. This masked + small imbalances and caused fragility (see issue #2402). As a result, + some journal entries (or CSV rules) that worked with hledger <1.50, are + now rejected with an "unbalanced transaction" error. If you hit this + problem, it's easy to fix: + + o You can restore the old behaviour, by adding --txn-balancing=old to + the command or to your ~/.hledger.conf file. This lets you keep us- + ing old journals unchanged, though without the above benefits. + + o Or you can fix the problem entries (recommended). There are three + ways, use whichever seems best: + + 1. make cost amounts more precise (add more/better decimal digits) + + 2. or make non-cost amounts less precise (remove unnecessary decimal + digits that are raising the precision) + + 3. or add a posting to absorb the imbalance (eg "expenses:rounding". + Remember that one posting may omit the amount; that's convenient + here.) + + Tags + Tags are a way to add extra labels or data fields to transactions, + postings, or accounts. They are usually a word or hyphenated word, im- + mediately followed by a full colon, written within the comment of a + transaction, a posting, or an account directive. (Yes, storing data in + comments is slightly weird!) + + You can write each tag on its own comment line, or multiple tags on one + line, separated by commas. Tags can also have a value, which is any + text after the colon until the next comma or end of line, excluding + surrounding whitespace. (hledger tag values can't contain commas.) If + the same tag name appears multiple times in a comment, each name:value + pair is preserved. + + An example: in this journal there are six tags, one of them with a + value: + + account assets:checking ; accounttag: + account expenses:food + + 2017/1/16 bought groceries ; transactiontag: + ; transactiontag2: + assets:checking $-1 + ; posting-tag-1:, (belongs to the posting above) + expenses:food $1 ; posting-tag-2:, posting-tag-3: with a value + + Querying with tags + Tags are most often used to select a subset of data; you can match + tagged things by tag name and or tag value with a tag: query. (See + queries below.) + + When querying for tag names or values, note that postings inherit tags + from their transaction and from their account, and transactions acquire + tags from their postings. So in the example above, - the assets:check- + ing posting effectively has four tags (one of its own, one from the ac- + count, two from the transaction) - the expenses:food posting effec- + tively has four tags (two of its own, two from the transaction) - the + transaction effectively has all six tags (two of its own, and two from + each posting) + + Displaying tags + You can use the tags command to list tag names or values. + + The print command also shows tags. + + You can use --pivot to display tag values in other reports, in various + ways (eg appended to account names, like pseudo subaccounts). + + When to use tags ? + Tags provide more dimensions of categorisation, complementing accounts + and transaction descriptions. When to use each of these is somewhat a + matter of taste. Accounts have the most built-in support, and regex + queries on descriptions are also quite powerful. So you may not need + tags at all. But if you want to track multiple cross-cutting cate- + gories, they can be a good fit. For example, you could tag trip-re- + lated transactions with trip: YEAR:PLACE, without disturbing your usual + account categories. + + Tag names + What is allowed in a tag name ? Currently, most non-whitespace charac- + ters. Eg : is a valid tag. + + For extra error checking, you can declare valid tag names with the tag + directive, and then enforce these with the check command. + + But note that tags are detected quite loosely at present, sometimes + where you didn't intend them. Eg ; see https://foo.com contains a + https tag with value //foo.com. + + Special tags + Some tag names have special significance to hledger. They are ex- + plained elsewhere, but here's a quick reference: + + type -- declares an account's type + date -- overrides a posting's date + date2 -- overrides a posting's secondary date + assert -- appears on txns generated by close --assert + retain -- appears on txns generated by close --retain + start -- appears on txns generated by close --migrate/--close/--open/--assign + t -- appears on postings generated from timedot letters + + generated-transaction -- appears on txns generated by a periodic rule + modified-transaction -- appears on txns which have had auto postings added + generated-posting -- appears on generated postings + cost-posting -- appears on postings which have (or could have) a cost, + and which have equivalent conversion postings in the transaction + conversion-posting -- appears on postings which are to a V/Conversion account + and which have an equivalent cost posting in the transaction + + The second group above (generated-transaction, etc.) are normally hid- + den, with a _ prefix added. This means print doesn't show them by de- + fault; but you can still use them in queries. You can add the --ver- + bose-tags flag to make them visible, which can be useful for trou- + bleshooting. + + 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 spe- + cific 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 di- + rectives: + + 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 bud- ~ + get goals + Generate extra postings on existing = + transactions + CHECKING FOR ERRORS: + Define valid entities to provide more account, commodity, payee, tag + error checking + REPORTING: + Declare accounts' type and display order account + Declare commodity display styles commodity + Declare market prices P + + Directives and multiple files + Directives vary in their scope, ie which journal entries and which in- + put files they affect. Most often, a directive will affect the follow- + ing 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 di- + rectives in your files. + + Directive effects + Here are all hledger's directives, with their effects and scope sum- + marised - nine main directives, plus four others which we consider + non-essential: + + di- what it does ends + rec- at + tive file + end? + -------------------------------------------------------------------------------------- + ac- Declares an account, for checking all entries in all files; and N + count its display order and type. Subdirectives: any text, ignored. + alias Rewrites account names, in following entries until end of cur- Y + rent file or end aliases. Command line equivalent: --alias + com- Ignores part of the journal file, until end of current file or Y + ment end comment. + com- Declares up to four things: 1. a commodity symbol, for checking N,N,Y,Y + mod- all amounts in all files 2. the display style for all amounts + ity of this commodity 3. the decimal mark for parsing amounts of + this commodity, in the rest of this file and its children, if + there is no decimal-mark directive 4. the precision to use for + balanced-transaction checking in this commodity, in this file + and its children. Takes precedence over D. Subdirectives: + format (ignored). Command line equivalent: -c/--commodity-style + deci- Declares the decimal mark, for parsing amounts of all commodi- Y + mal-mark ties in following entries until next decimal-mark or end of cur- + rent file. Included files can override. Takes precedence over + commodity and D. + include Includes entries and directives from another file, as if they N + 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: + apply Prepends a common parent account to all account names, in fol- Y + account lowing 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). + Other Other directives from Ledger's file format are accepted but ig- + Ledger nored. + direc- + tives + + account directive + account directives can be used to declare accounts (ie, the places that + amounts are transferred from and to). Though not required, these dec- + larations can provide several benefits: + + o They can document your intended chart of accounts, providing a refer- + ence. + + o They can store additional account information as comments, or as tags + which can be used to filter or pivot reports. + + o They can restrict which accounts may be posted to by transactions, eg + in strict mode, which helps prevent errors. + + o They influence account display order in reports, allowing non-alpha- + betic sorting (eg Revenues to appear above Expenses). + + o They can help hledger know your accounts' types (asset, liability, + equity, revenue, expense), enabling reports like balancesheet and in- + comestatement. + + o They help with account name completion (in hledger add, hledger-web, + hledger-iadd, ledger-mode, etc.) + + They are written as the word account followed by a hledger-style ac- + count name. Eg: + + account assets:bank:checking + + Ledger-style indented subdirectives are also accepted, but ignored: + + account assets:bank:checking + format subdirective ; currently ignored + + Account comments + Text following two or more spaces and ; at the end of an account direc- + tive line, and/or following ; on indented lines immediately below it, + form comments for that account. They are ignored except they may con- + tain 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 + + 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 jour- + nal. Usually you'll find that error later, as an extra account in bal- + ance reports, or an incorrect balance when reconciling. + + In strict mode, enabled with the -s/--strict flag, or when you run + hledger check accounts, hledger will report an error if any transaction + uses an account name that has not been declared by an account direc- + tive. Some notes: + + o The declaration is case-sensitive; transactions must use the correct + account name capitalisation. + + o The account directive's scope is "whole file and below" (see direc- + tives). This means it affects all of the current file, and any files + it includes, but not parent or sibling files. The position of ac- + count directives within the file does not matter, though it's usual + to put them at the top. + + o Accounts can only be declared in journal files, but will affect in- + cluded files of all types. + + o It's currently not possible to declare "all possible subaccounts" + with a wildcard; every account posted to must be declared. + + o If you use the --infer-equity flag, you will also need declarations + for the account names it generates. + + Account display order + Account directives also cause hledger to display accounts in a particu- + lar order, not just alphabetically. Eg, here is a conventional order- + ing for the top-level accounts: + + account assets + account liabilities + account equity + account revenues + account expenses + + Now hledger displays them in that order: + + $ hledger accounts + assets + liabilities + equity + revenues + expenses + + If there are undeclared accounts, those will be displayed last, in al- + phabetical order. + + Sorting is done within each group of sibling accounts, at each level of + the account tree. Eg, a declaration like account parent:child influ- + ences child's position among its siblings. + + Note, it does not affect parent's position; for that, you need an ac- + count parent declaration. + + Sibling accounts are always displayed together; hledger won't display + x:y in between a:b and a:c. + + An account directive both declares an account as a valid posting tar- + get, and declares its display order; you can't easily do one without + the other. + + Account types + hledger knows that in accounting there are three main account types: + + Asset A things you own + Liability L things you owe + Equity E owner's investment, + balances the two + above + + and two more representing changes in these: + + Revenue R inflows (also known + as Income) + Expense X outflows + + hledger also uses a couple of subtypes: + + Cash C liquid assets + Conversion V commodity conver- + sions equity + + As a convenience, hledger will detect these types automatically from + english account names. But it's better to declare them explicitly by + adding a type: tag in the account directives. The tag's value can be + any of the types or one-letter abbreviations above. + + Here is a typical set of account type declarations. Subaccounts will + inherit their parent's type, or can override it: + + 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 + + This enables the easy balancesheet, balancesheetequity, cashflow and + incomestatement reports, and querying by type:. + + Tips: + + o You can list accounts and their types, for troubleshooting: + + $ hledger accounts --types [ACCTPAT] [type:TYPECODES] [-DEPTH] [--positions] + + o It's a good idea to declare at least one account for each account + type. Having some types declared and some inferred can disrupt cer- + tain reports. + + o The rules for inferring types from account names are as follows (us- + ing Regular expressions). + If they don't work for you, just ignore them and declare your types + with type: tags. + + If account's name contains this case insensitive 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 + + o As mentioned above, subaccounts will inherit a type from their parent + account. To be precise, an account's type is decided by the first of + these that exists: + + 1. A type: declaration for this account. + + 2. A type: declaration in the parent accounts above it, preferring + the nearest. + + 3. An account type inferred from this account's name. + + 4. An account type inferred from a parent account's name, preferring + the nearest parent. + + 5. Otherwise, it will have no type. + + o Account aliases can disrupt account types. + + 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: + + o expanding shorthand account names to their full form, allowing easier + data entry and a less verbose journal + + o adapting old journals to your current chart of accounts + + o experimenting with new account organisations, like a new hierarchy + + o combining two accounts into one, eg to see their sum or difference on + one line + + o 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 cor- + rectly, but you can also generate invalid account names with them; more + on this below. + + See also Rewrite account names. + + 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 re- + place any occurrence of the old account name with the new one. Subac- + counts 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" + + 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 ex- + pression.) + + Eg: + + alias /REGEX/ = REPLACEMENT + + or: + + $ hledger --alias '/REGEX/=REPLACEMENT' ... + + Any part of an account name matched by REGEX will be replaced by RE- + PLACEMENT. 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. + + 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: + + o the nearest alias declaration before/above the entry is applied first + + o the next alias before/above that will be be applied next, and so on + + o aliases defined after/below the entry do not affect it. + + This gives nearby aliases precedence over distant ones, and helps pro- + vide semantic stability - aliases will keep working the same way inde- + pendent 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. + + 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. In- + cluding 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 + + end aliases directive + You can clear (forget) all currently defined aliases (seen in the jour- + nal so far, or defined on the command line) with this directive: + + end aliases + + 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 exam- + ple, 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 + + 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 ef- + fect. + + 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, renam- + ing it by an alias could prevent or alter that. + + If you are using account aliases and the type: query is not matching + accounts as you expect, try troubleshooting with the accounts command, + eg something like: + + $ hledger accounts --types -1 --alias assets=bassetts + + commodity directive + The commodity directive performs several functions: + + 1. It declares which commodity symbols may be used in the journal, en- + abling useful error checking with strict mode or the check command. + See Commodity error checking below. + + 2. It declares how all amounts in this commodity should be displayed, + eg how many decimals to show. See Commodity display style above. + + 3. (If no decimal-mark directive is in effect:) It sets the decimal + mark to expect (period or comma) when parsing amounts in this com- + modity, in this file and files it includes, from the directive until + end of current file. See Decimal marks above. + + 4. It declares the precision with which this commodity's amounts should + be compared when checking for balanced transactions, anywhere in + this file and files it includes, until end of current file. + + Declaring commodities solves several common parsing/display problems, + so we recommend it. + + Note that effects 3 and 4 above end at the end of the directive's file, + and will not affect sibling or parent files. So if you are relying on + them (especially 4) and using multiple files, placing your commodity + directives in a top-level parent file might be important. Or, keep + your decimal marks unambiguous and your entries well balanced and pre- + cise. + + (Related: #793) + + Commodity directive syntax + A commodity directive is normally the word commodity followed by a sam- + ple amount (and optionally a comment). Only the amount's symbol and + the number's format is significant. Eg: + + commodity $1000.00 + commodity 1.000,00 EUR + commodity 1 000 000.0000 ; the no-symbol commodity + + Commodities do not have tags (tags in the comment will be ignored). + + A commodity directive's sample amount must always include a period or + comma decimal mark (this rule helps disambiguate decimal marks and + digit group marks). If you don't want to show any decimal digits, + write the decimal mark at the end: + + commodity 1000. AAAA ; show AAAA with no decimals + + Commodity symbols containing spaces, numbers, or punctuation must be + enclosed in double quotes, as usual: + + commodity 1.0000 "AAAA 2023" + + Commodity directives normally include a sample amount, but can declare + only a symbol (ie, just function 1 above): + + commodity $ + commodity INR + commodity "AAAA 2023" + commodity "" ; the no-symbol commodity + + Commodity directives may also be written with an indented format subdi- + rective, 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 + + Commodity error checking + In strict mode (-s/--strict) (or when you run hledger check commodi- + ties), 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). + + 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). + + include directive + You can pull in the content of additional files by writing an include + directive, like this: + + include SOMEFILE + + This has the same effect as if SOMEFILE's content was inlined at this + point. (With any include directives in SOMEFILE processed similarly, + recursively.) + + Only journal files can include other files. They can include journal, + timeclock or timedot files, but not CSV files. + + If the file path begins with a tilde, that means your home directory: + include ~/main.journal. + + If it begins with a slash, it is an absolute path: include + /home/user/main.journal. Otherwise it is relative to the including + file's folder: include ../finances/main.journal. + + Also, the path may have a file type prefix to force a specific file + format, overriding the file extension(s) (as described in Data for- + mats): include timedot:notes/2023.md. + + The path may contain glob patterns to match multiple files. hledger's + globs are similar to zsh's: ? to match any character; [a-z] to match + any character in a range; * to match zero or more characters that + aren't a path separator (like /); ** to match zero or more subdirecto- + ries and/or zero or more characters at the start of a file name; etc. + Also, hledger's globs always exclude the including file itself. So, + you can do + + o include *.journal to include all other journal files in the current + directory (excluding dot files) + + o include **.journal to include all other journal files in this direc- + tory and below (excluding dot directories/files) + + o include timelogs/2???.timedot to include all timedot files named like + a year number. + + There is a limitation: hledger's globs always exclude paths involving + dot files or dot directories. This is a workaround for unavoidable dot + directory traversal; you can disable it and revert to older behaviour + with the --old-glob flag, for now. + + If you are using many, or deeply nested, include files, and have an er- + ror that's hard to pinpoint: a good troubleshooting command is hledger + files --debug=6 (or 7). + + P directive + The P directive declares a market price, which is a conversion rate be- + tween 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. Ex- + amples: + + # 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. + + 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. + + tag directive + tag TAGNAME + + This directive can be used to declare a limited set of tag names al- + lowed in tags. TAGNAME should be a valid tag name (no spaces). Eg: + + tag item-id + + Any indented subdirectives are currently ignored. + + The "tags" check will report an error if any undeclared tag name is + used. It is quite easy to accidentally create a tag through normal use + of colons in comments; if you want to prevent this, you can declare and + check your tags . + + Periodic transactions + The ~ directive declares a "periodic rule" which generates temporary + extra transactions, usually recurring at some interval, when hledger is + run with the --forecast flag. These "forecast transactions" are useful + for forecasting future activity. They exist only for the duration of + the report, and only when --forecast is used; they are not saved in the + journal file by hledger. + + Periodic rules also have a second use: with the --budget flag they set + budget goals for budgeting. + + Periodic rules can be a little tricky, so before you use them, read + this whole section, or at least the following tips: + + 1. Two spaces accidentally added or omitted will cause you trouble - + read about this below. + + 2. For troubleshooting, show the generated transactions with hledger + print --forecast tag:generated or hledger register --forecast + tag:generated. + + 3. Forecasted transactions will begin only after the last non-fore- + casted 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 im- + provement, 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. + + 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-pe- + riod reports, just interpreted differently; there, it specifies report + periods; here it specifies recurrence dates (the periods' start dates). + + 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 re- + sults 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. + + 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 acciden- + tally 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, + + o Do write two spaces between your period expression and your transac- + tion description, if any. + + o Don't accidentally write two spaces in the middle of your period ex- + pression. + + Auto postings + The = directive declares an "auto posting rule", which adds extra post- + ings to existing transactions. (Remember, postings are the account + name & amount lines below a transaction's date & description.) + + In the journal, an auto posting rule looks quite like a transaction, + but instead of date and description it has = (mnemonic: "match") and a + query, like this: + + = QUERY + ACCOUNT AMOUNT + ... + + Queries are just like command line queries; an account name substring + is most common. Query terms containing spaces should be enclosed in + single or double quotes. + + Each = rule works like this: when hledger is run with the --auto flag, + wherever the QUERY matches a posting in the journal, the rule's post- + ings are added to that transaction, immediately below the matched post- + ing. Note these generated postings are temporary, existing only for + the duration of the report, and only when --auto is used; they are not + saved in the journal file by hledger. + + The postings can contain the special string %account which will be ex- + panded to the account name of the matched account. + + Generated postings' amounts can depend on the matched posting's amount. + So auto postings can be useful for, eg, adding tax postings with a + standard percentage. AMOUNT can be: + + o a number with no commodity symbol, like 2. The matched posting's + commodity symbol will be added to this. + + o a normal amount with a commodity symbol, like $2. This will be used + as-is. + + o an asterisk followed by a number, like *2. This will multiply the + matched posting's amount (and total price, if any) by the number. + + o an asterisk followed by an amount with commodity symbol, like *$2. + This multiplies and also replaces the commodity symbol with this new + one. + + Some examples: + + ; every time I buy food, schedule a dollar donation + = expenses:food + (liabilities:charity) $-1 + + ; when I buy a gift, also deduct that amount from a budget envelope subaccount + = expenses:gifts + assets:checking:gifts *-1 + assets:checking *1 + + 2017/12/1 + expenses:food $10 + assets:checking + + 2017/12/14 + expenses:gifts $20 + assets:checking + + $ hledger print --auto + 2017-12-01 + expenses:food $10 + assets:checking + (liabilities:charity) $-1 + + 2017-12-14 + expenses:gifts $20 + assets:checking + assets:checking:gifts -$20 + assets:checking $20 + + Note that depending fully on generated data such as this has some draw- + backs - it's less portable, less future-proof, less auditable by oth- + ers, and less robust (eg your balance assertions will depend on whether + you use or don't use --auto). An alternative is to use auto postings + in "one time" fashion - use them to help build a complex journal entry, + view it with hledger print --auto, and then copy that output into the + journal file to make it permanent. + + 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). + + 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. + + Auto postings and transaction balancing / inferred amounts / balance asser- + tions + Currently, auto postings are added: + + o after missing amounts are inferred, and transactions are checked for + balancedness, + + o 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. + + Auto posting tags + Automated postings will have some extra tags: + + o generated-posting:= QUERY - shows this was generated by an auto post- + ing rule, and the query + + o _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: + + o modified: - this transaction was modified + + o _modified: - a hidden tag not appearing in the comment; this transac- + tion was modified "just now". + + Auto postings on forecast transactions only + Tip: you can can make auto postings that will apply to forecast trans- + actions but not recorded transactions, by adding tag:_generated-trans- + action to their QUERY. This can be useful when generating new journal + entries to be saved in the journal. + + 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. + + 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 assign- + ment). + + Downsides: using balance assignments makes your journal less explicit; + to know the exact amount posted, you have to run hledger or do the cal- + culations yourself, instead of just reading it. Also balance assign- + ments' forcing of balances can hide errors. These things make your fi- + nancial data less portable, less future-proof, and less trustworthy in + an audit. + + Balance assignments and costs + A cost in a balance assignment will cause the calculated amount to have + that cost attached: + + 2019/1/1 + (a) = $1 @ 2 + + $ hledger print --explicit + 2019-01-01 + (a) $1 @ 2 = $1 @ 2 + + 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. + + Bracketed posting dates + For setting posting dates and secondary posting dates, Ledger's brack- + eted 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 syn- + tax, 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. + + 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 jour- + nal. This effect lasts until the next D directive, or the end of the + current file. + + For compatibility/historical reasons, D also acts like a commodity di- + rective (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 deci- + mal 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 di- + rective 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 usu- + ally 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. + + 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 direc- + tive 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 included 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. + + 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 subse- + quent 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 trust- + worthy in an audit. Such dates can get separated from their corre- + sponding Y directive, eg when evaluating a region of the journal in + your editor. A missing Y directive makes reports dependent on today's + date. + + Secondary dates + A secondary date is written after the primary date, following an equals + sign: DATE1=DATE2. If the year is omitted, the primary date's year is + assumed. When running reports, the primary (left side) date is used by + default, but with the --date2 flag (--aux-date or--effective also work, + for Ledger users), the secondary (right side) date will be used in- + stead. + + The meaning of secondary dates is up to you. Eg it could be "primary + is the bank's clearing date, secondary is the date the transaction was + initiated, if different". + + In practice, this feature usually adds confusion: + + o You have to remember the primary and secondary dates' meaning, and + follow that consistently. + + o It splits your bookkeeping into two modes, and you have to remember + which mode is appropriate for a given report. + + o Usually your balance assertions will work with only one of these + modes. + + o It makes your financial data more complicated, less portable, and + less clear in an audit. + + o It interacts with every feature, creating an ongoing cost for imple- + mentors. + + o It distracts new users and supporters. + + o Posting dates are simpler and work better. + + So secondary dates are officially deprecated in hledger, remaining only + as a Ledger compatibility aid; we recommend using posting dates in- + stead. + + Star comments + Lines beginning with * (star/asterisk) are also comment lines. This + feature allows Emacs users to insert org headings in their journal, al- + lowing 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. + + Valuation expressions + Ledger allows a valuation function or value to be written in double + parentheses after an amount. hledger ignores these. + + Virtual postings + A posting with parentheses around the account name, like (some:account) + 10, is called an unbalanced virtual posting. These postings do not + participate in transaction balancing. (And if you write them without + an amount, a zero amount is always inferred.) These can occasionally + be convenient for special circumstances, but they violate double entry + bookkeeping and make your data less portable across applications, so + many people avoid using them at all. + + A posting with brackets around the account name ([some:account]) is + called a balanced virtual posting. The balanced virtual postings in a + transaction must add up to zero, just like ordinary postings, but sepa- + rately from them. These are not part of double entry bookkeeping ei- + ther, 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. + + 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. + + Other cost/lot notations + A slight digression for Ledger and Beancount users. + + Ledger has a number of cost/lot-related notations: + + o @ UNITCOST and @@ TOTALCOST + + o expresses a conversion rate, as in hledger + + o when buying, also creates a lot that can be selected at selling + time + + o (@) UNITCOST and (@@) TOTALCOST (virtual cost) + + o like the above, but also means "this cost was exceptional, don't + use it when inferring market prices". + + o {=UNITCOST} and {{=TOTALCOST}} (fixed price) + + o when buying, means "this cost is also the fixed value, don't let it + fluctuate in value reports" + + o {UNITCOST} and {{TOTALCOST}} (lot price) + + o can be used identically to @ UNITCOST and @@ TOTALCOST, also cre- + ates a lot + + o when selling, combined with @ ..., selects an existing lot by its + cost basis. Does not check if that lot is present. + + o [YYYY/MM/DD] (lot date) + + o when buying, attaches this acquisition date to the lot + + o when selling, selects a lot by its acquisition date + + o (SOME TEXT) (lot note) + + o when buying, attaches this note to the lot + + o when selling, selects a lot by its note + + Currently, hledger + + o accepts any or all of the above in any order after the posting amount + + o supports @ and @@ + + o treats (@) and (@@) as synonyms for @ and @@ + + o and ignores the rest. (This can break transaction balancing.) + + Beancount has simpler notation and different behaviour: + + o @ UNITCOST and @@ TOTALCOST + + o expresses a cost without creating a lot, as in hledger + + o when buying (acquiring) or selling (disposing of) a lot, and com- + bined with {...}: is not used except to document the cost/selling + price + + o {UNITCOST} and {{TOTALCOST}} + + o when buying, expresses the cost for transaction balancing, and also + creates a lot with this cost basis attached + + o when selling, + + o selects a lot by its cost basis + + o raises an error if that lot is not present or can not be selected + unambiguously (depending on booking method configured) + + o expresses the selling price for transaction balancing + + o {}, {YYYY-MM-DD}, {"LABEL"}, {UNITCOST, "LABEL"}, {UNITCOST, + YYYY-MM-DD, "LABEL"} + + o when selling, other combinations of date/cost/label, like the + above, are accepted for selecting the lot. + + Currently, hledger + + o supports @ and @@ + + o accepts the {UNITCOST}/{{TOTALCOST}} notation, but ignores it + + o and rejects the rest. + +CSV + hledger can read transactions from CSV (comma-separated values) files. + More precisely, it can read DSV (delimiter-separated values), from a + file or standard input. Comma-separated, semicolon-separated and + tab-separated are the most common variants, and hledger will recognise + these three automatically based on a .csv, .ssv or .tsv file name ex- + tension or a csv:, ssv: or tsv: file path prefix. + + (To learn about producing CSV or TSV output, see Output format.) + + 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 attrib- + utes. + + By default, hledger expects this rules file to be named like the CSV + file, with an extra .rules extension added, in the same directory. Eg + when asked to read foo/FILE.csv, hledger looks for foo/FILE.csv.rules. + You can specify a different rules file with the --rules option. + + At minimum, the rules file must identify the date and amount fields, + and often it also specifies the date format and how many header lines + there are. Here's a simple CSV file and a rules file for it: + + Date, Description, Id, Amount + 12/11/2019, Foo, 123, 10.23 + + # basic.csv.rules + skip 1 + fields date, description, , amount + date-format %d/%m/%Y + + $ hledger print -f basic.csv + 2019-11-12 Foo + expenses:unknown 10.23 + income:unknown -10.23 + + There's an introductory Tutorial: Import CSV data on hledger.org, and + more CSV rules examples below, and a larger collection at + https://github.com/simonmichael/hledger/tree/master/examples/csv. + + 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 + archive optionally enable an archive of imported files + encoding optionally declare which text encoding the + data has + separator declare the field separator, instead of rely- + ing on file extension + decimal-mark declare the decimal mark used in CSV amounts, + when ambiguous + 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 + skip (at top level) skip header line(s) at start of + file + fields list name CSV fields for easy reference, and op- + tionally 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 + skip (inside an if rule) skip current record(s) + end (inside an if rule) skip all remaining records + balance-type select which type of balance assertions/as- + signments to generate + include inline another CSV rules file + + Working with CSV tips can be found below, including How CSV rules are + evaluated. + + 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 pro- + vides some extra features. For one, the data file can be missing, + without causing an error; it is just considered empty. + + For more flexibility, add a source rule, which lets you specify a dif- + ferent data file: + + source ./Checking1.csv + + If the file does not exist, it is just considered empty, without rais- + ing an error. + + If you specify just a file name with no path, hledger will look for it + in the ~/Downloads folder: + + source Checking1.csv + + You can use a glob pattern, to avoid specifying the file name exactly: + + source Checking1*.csv + + This has another benefit: if the pattern matches multiple files, + hledger will read the newest (most recently modified) one. This avoids + problems if you have downloaded a file multiple times without cleaning + up. + + All this enables a convenient workflow where can you just download CSV + files, then run hledger import rules/*. + + See also "Working with CSV > Reading files specified by rule". + + Data cleaning / data generating commands + After source's file pattern, you can write | (pipe) and a data cleaning + command (or command pipeline). If hledger's CSV rules aren't enough, + you can pre-process the downloaded data here with a shell command or + script, to make it more suitable for conversion. The command will be + executed by your default shell, in the directory of the rules file, + will receive the data file's content as standard input, and should out- + put zero or more lines of character-separated-values, suitable for con- + version by the CSV rules. + + Examples: + + source ./paypal.json | paypalcsv + source data/simplefin.json | simplefincsv - 'chase.*card' + source OfxDownload*.csv | grep -vE '^(([^,]*,){6}[^,]*|)$' | sort -t, -n +2 + source History_for_Account_Z20144832*.csv # | grep -E '^([^,]*,){12}[^,]*$' | sed -E -e 's/^ //' -e 's/\.([0-9]),/.\10,/g' -e 's/,([0-9]+),/,\1.00,/g' + + Or, after source you can write | and a data generating command (with no + file pattern before the |). This command receives no input, and should + output zero or more lines of character-separated values, suitable for + conversion by the CSV rules. + + Examples: + + source | paypaljson | paypalcsv + source | paypalcsv data/paypal.json + source | simplefinjson >data/simplefin.json && simplefincsv data/simplefin.json 'chase.*card' + source | simplefincsv data/simplefin.json 'unify.*checking' + + (paypal* and simplefin* scripts are in bin/) + + Whenever hledger runs one of these commands, it will echo the command + on stderr. If the command produces error output, but exits success- + fully, hledger will show the error output as a warning. If the command + fails, hledger will fail and show the error output in the error mes- + sage. + + Added in 1.50; experimental. + + archive + With archive added to a rules file, the import command will archive + each successfully processed data file or data command output in a + nearby data/ directory. The archive file name will be based on the + rules file and the data file's modification date and extension (or for + a data-generating command, the current date and the ".csv" extension). + The original data file, if any, will be removed. + + Also, in this mode import will prefer the oldest file matched by the + source rule's glob pattern, not the newest. (So if there are multiple + downloads, they will be imported and archived oldest first.) + + Archiving is optional, but it can be useful for troubleshooting your + CSV rules, regenerating entries with improved rules, checking for vari- + ations in your bank's CSV, etc. + + Added in 1.50; experimental. + + encoding + encoding ENCODING + + hledger normally expects non-ascii text to be using the system locale's + text encoding. If you need to read CSV files which have some other en- + coding, you can do it by adding encoding ENCODING to your CSV rules. + Eg: encoding iso-8859-1. + + The following encodings are supported: + + ascii, utf-8, utf-16, utf-32, iso-8859-1, iso-8859-2, iso-8859-3, + iso-8859-4, iso-8859-5, iso-8859-6, iso-8859-7, iso-8859-8, iso-8859-9, + iso-8859-10, iso-8859-11, iso-8859-13, iso-8859-14, iso-8859-15, + iso-8859-16, cp1250, cp1251, cp1252, cp1253, cp1254, cp1255, cp1256, + cp1257, cp1258, koi8-r, koi8-u, gb18030, macintosh, jis-x-0201, + jis-x-0208, iso-2022-jp, shift-jis, cp437, cp737, cp775, cp850, cp852, + cp855, cp857, cp860, cp861, cp862, cp863, cp864, cp865, cp866, cp869, + cp874, cp932. + + Added in 1.42. + + separator + You can use the separator rule to read other kinds of character-sepa- + rated 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 automat- + ically, and you won't need this rule. + + 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. + + 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/pack- + age/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 + + Note currently there is no locale awareness for things like %b, and + setting LC_TIME won't help. + + 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. + + 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 transac- + tions in correct order. + + # same-day CSV records are newest first + newest-first + + 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 + + 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. + + 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: + + o There must be least two items in the list (at least one comma). + + o Field names may not contain spaces. Spaces before/after field names + are optional. + + o Field names may contain _ (underscore) or - (hyphen). + + o 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 re- + placed 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 "bal- + ance" field balance_ to avoid directly setting hledger's balance field + (and generating a balance assertion). + + 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 inter- + polate 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: + + o Interpolation strips outer whitespace (so a CSV value like " 1 " be- + comes 1 when interpolated) (#1051). + + o Interpolations always refer to a CSV field - you can't interpolate a + hledger field. (See Referencing other fields below). + + 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 auto- + matically recognise column headings in a CSV file), by writing arbi- + trary 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 as- + signment, 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 hap- + pens when you assign values to them: + + date field + Assigning to date sets the transaction date. + + date2 field + date2 sets the transaction's secondary date, if any. + + status field + status sets the transaction's status, if any. + + code field + code sets the transaction's code, if any. + + description field + description sets the transaction's description, if any. + + comment field + comment sets the transaction's comment, if any. + + commentN, where N is a number, sets the Nth posting's comment. + + You can assign multi-line comments by writing literal \n in the code. + A comment starting with \n will begin on a new line. + + Comments can contain tags, as usual. + + Posting comments can also contain a posting date. A secondary date, or + a year-less date, will be ignored. + + 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"). + + amount field + There are several ways to set posting amounts from CSV, useful in dif- + ferent 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: + + o 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". + + o 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. + + o 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 noth- + ing. + + o hledger assumes both CSV fields contain unsigned numbers, and it + automatically negates the amount-out values. + + o 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 com- + plex transactions. The posting numbers don't have to be consecu- + tive; 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 flexibil- + ity, use an if rule to set amounts conditionally. See "Working with + CSV > Setting amounts" below for more on this and on amount-setting + generally. + + 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. + + balance field + balanceN sets a balance assertion amount (or if the posting amount is + left empty, a balance assignment) on posting N. + + balance is a compatibility spelling for hledger <1.17; it is equivalent + to balance1. + + You can adjust the type of assertion/assignment with the balance-type + rule (see below). + + See the Working with CSV tips below for more about setting amounts and + currency. + + if block + Rules can be applied conditionally, depending on patterns in the CSV + data. This allows flexibility; in particular, it is how you can cate- + gorise transactions, selecting an appropriate account name based on + their description (for example). There are two ways to write condi- + tional 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 ap- + plied. They are usually field assignments, but the following special + rules may also be used within an if block: + + o skip - skips the matched CSV record (generating no transaction from + it) + + o 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 + + Matchers + There are two kinds of matcher: + + 1. A whole record matcher is simplest: it is just a word, single-line + text fragment, or other regular expression, which hledger will try + to match case-insensitively anywhere within the CSV record. + Eg: whole foods. + + 2. A field matcher has a percent-prefixed CSV field number or name be- + fore the pattern. + Eg: %3 whole foods or %description whole foods. + hledger will try to match the pattern just within the named CSV field. + + When using these, there's two things to be aware of: + + 1. Whole record matchers don't see the exact original record; they see + a reconstruction of it, in which values are comma-separated, and + quotes enclosing values and whitespace outside those quotes are re- + moved. + Eg when reading an SSV record like: 2023-01-01 ; "Acme, Inc. " ; 1,000 + the whole record matcher sees instead: 2023-01-01,Acme, Inc. ,1,000 + + 2. Field matchers expect either a CSV field number, or a CSV field name + declared with fields. (Don't use a hledger field name here, unless + it is also a CSV field name.) A non-CSV field name will cause the + matcher to match against "" (the empty string), and does not raise + an error, allowing easier reuse of common rules with different CSV + files. + + You can also prefix a matcher with ! (and optional space) to negate it. + Eg ! whole foods, ! %3 whole foods, !%description whole foods will + match if "whole foods" is NOT present. Added in 1.32. + + The pattern is, as usual in hledger, a POSIX extended regular expres- + sion that also supports GNU word boundaries (\b, \B, \<, \>) and noth- + ing else. If you have trouble with it, see "Regular expressions" in + the hledger manual (https://hledger.org/hledger.html#regular-expres- + sions). + + Multiple matchers + When an if block has multiple matchers, each on its own line, + + o By default they are OR'd (any of them can match). + + o Matcher lines beginning with & (or &&, since 1.42) are AND'ed with + the matcher above (all in the AND'ed group must match). + + o Matcher lines beginning with & ! (since 1.41, or && !, since 1.42) + are first negated and then AND'ed with the matcher above. + + You can also combine multiple matchers one the same line separated by + && (AND) or && ! (AND NOT). Eg %description amazon && %date 2025-01-01 + will match only when the description field contains "amazon" and the + date field contains "2025-01-01". Added in 1.42. + + Match groups + Added in 1.32 + + Matchers can define match groups: parenthesised portions of the regular + expression which are available for reference in field assignments. + Groups are enclosed in regular parentheses (( and )) and can be nested. + Each group is available in field assignments using the token \N, where + N is an index into the match groups for this conditional block (e.g. + \1, \2, etc.). + + Example: Warp credit card payment postings to the beginning of the + billing period (Month start), to match how they are presented in state- + ments, 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 + + if table + "if tables" are an alternative to if blocks; they can express many + matchers and field assignments in a more compact tabular format, like + this: + + if,HLEDGERFIELD1,HLEDGERFIELD2,... + MATCHERA,VALUE1,VALUE2,... + MATCHERB && MATCHERC,VALUE1,VALUE2,... (*since 1.42*) + ; Comment line that explains MATCHERD + MATCHERD,VALUE1,VALUE2,... + + + The first character after if is taken to be this if table's field sepa- + rator. It is unrelated to the separator used in the CSV file. It + should be a non-alphanumeric character like , or | that does not appear + anywhere else in the table (it should not be used in field names or + matchers or values, and it cannot be escaped with a backslash). + + Each line must contain the same number of separators; empty values are + allowed. Whitespace can be used in the matcher lines for readability + (but not in the if line, currently). You can use the comment lines in + the table body. The table must be terminated by an empty line (or end + of file). + + An if table like the above is interpreted as follows: try all of the + lines with matchers; whenever a line with matchers succeeds, assign all + of the values on that line to the corresponding hledger fields; If mul- + tiple lines match, later lines will override fields assigned by the + earlier ones - just like the sequence of if blocks would behave. + + If table presented above is equivalent to this sequence of if blocks: + + if MATCHERA + HLEDGERFIELD1 VALUE1 + HLEDGERFIELD2 VALUE2 + ... + + if MATCHERB && MATCHERC + HLEDGERFIELD1 VALUE1 + HLEDGERFIELD2 VALUE2 + ... + + ; Comment line which explains MATCHERD + if MATCHERD + HLEDGERFIELD1 VALUE1 + HLEDGERFIELD2 VALUE2 + ... + + Example: + + if,account2,comment + atm transaction fee,expenses:business:banking,deductible? check it + %description groceries,expenses:groceries, + ;; Comment line that desribes why this particular date is special + 2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out + + 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 + + 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 + + Working with CSV + Some tips: + + 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. + + 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: + + o Values may be enclosed in double quotes, or not. Enclosing in single + quotes is not allowed. (Eg 'A','B' is rejected.) + + o When values are enclosed in double quotes, spaces outside the quotes + are not allowed. (Eg "A", "B" is rejected.) + + o 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 trans- + form it before reading with hledger. Try using sed, or a more permis- + sive CSV parser like python's csv lib. + + 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. + + 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 + + Reading multiple CSV files + If you use multiple -f options to read multiple CSV files at once, + hledger will look for a correspondingly-named rules file for each CSV + file. But if you specify a rules file with --rules, that rules file + will be used for all the CSV files. + + 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 file- + names 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 transac- + tions + + 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 noth- + ing, 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. + + Valid transactions + After reading a CSV file, hledger post-processes and validates the gen- + erated 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 as- + sertions generated from CSV right away, pipe into another hledger: + + $ hledger -f file.csv print | hledger -f- print + + 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: + + o https://hledger.org/cookbook.html#setups-and-workflows + + o https://plaintextaccounting.org -> data import/conversion + + Setting amounts + Continuing from amount field above, here are more tips for amount-set- + ting: + + 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 usu- + ally 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 con- + taining 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. + + 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): + + o If an amount value begins with a plus sign: + that will be removed: +AMT becomes AMT + + o If an amount value is parenthesised: + it will be de-parenthesised and sign-flipped: (AMT) becomes -AMT + + o 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 + + o If an amount value contains just a sign (or just a set of parenthe- + ses): + 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. + + 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. + + Amount decimal places + When you are reading CSV data, eg with a command like hledger -f + foo.csv print, hledger will infer each commodity's decimal precision + (and other commodity display styles) from the amounts - much as when + reading a journal file without commodity directives (see the link). + + Note, the commodity styles are not inferred from the numbers in the + original CSV data; rather, they are inferred from the amounts generated + by the CSV rules. + + When you are importing CSV data with the import command, eg hledger im- + port foo.csv, there's another step: import tries to make the new en- + tries conform to the journal's existing styles. So for each commodity + - let's say it's EUR - import will choose: + + 1. the style declared for EUR by a commodity directive in the journal + + 2. otherwise, the style inferred from EUR amounts in the journal + + 3. otherwise, the style inferred from EUR amounts generated by the CSV + rules. + + TLDR: if import is not generating the precisions or styles you want, + add a commodity directive to specify them. + + 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 lit- + eral "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 + + How CSV rules are evaluated + Here's how to think of CSV rules being evaluated. If you get a confus- + ing error while reading a CSV file, it may help to try to understand + which of these steps is failing: + + 1. Any included rules files are inlined, from top to bottom, depth + first (scanning each included file for further includes, recur- + sively, before proceeding). + + 2. Top level rules (date-format, fields, newest-first, skip etc) are + read, top to bottom. "Top level rules" means non-conditional rules. + If a rule occurs more than once, the last one wins; except for + skip/end rules, where the first one wins. + + 3. The CSV file is read as text. Any non-ascii characters will be de- + coded using the text encoding specified by the encoding rule, other- + wise the system locale's text encoding. + + 4. Any top-level skip or end rule is applied. skip [N] immediately + skips the current or next N CSV records; end immediately skips all + remaining CSV records (not normally used at top level). + + 5. Now any remaining CSV records are processed. For each CSV record, + in file order: + + o Is there a conditional skip/end rule that applies for this record + ? Search the if blocks, from top to bottom, for a succeeding one + containing a skip or end rule. If found, skip the specified num- + ber of CSV records, then continue at 5. + Otherwise... + + o Do some basic validation on this CSV record (eg, check that it + has at least two fields). + + o For each hledger field (date, description, account1, etc.): + + 1. Get the field's assigned value, first searching top level as- + signments, made directly or by the fields rule, then assign- + ments made inside succeeding if blocks. If there are more + than one, the last one wins. + + 2. Compute the field's actual value (as text), by interpolating + any %CSVFIELD references within the assigned value; or by + choosing a default value if there was no assignment. + + o Generate a hledger transaction from the hledger field values, + parsing them if needed (eg from text to an amount). + + This is all done by the CSV reader, one of several readers hledger can + use to read transactions from an input file. When all input files have + been read successfully, their transactions are passed to whichever + hledger command the user specified. + + Well factored rules + Some things than can help reduce duplication and complexity in rules + files: + + o Extracting common rules usable with multiple CSV files into a com- + mon.rules, and adding include common.rules to each CSV's rules file. + + o Splitting if blocks into smaller if blocks, extracting the frequently + used parts. + + CSV rules examples + 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 neces- + sary 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 read- + ing directly from CSV, but they will be checked if these entries are + imported into a journal file. + + Coinbase + A simple example with some CSV from Coinbase. The spot price is + recorded using cost notation. The legacy amount field name conve- + niently 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 + + Amazon + Here we convert amazon.com order history, and use an if block to gener- + ate 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 + + 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: + +Timeclock + hledger can read time logs in the timeclock time logging format of + timeclock.el. As with Ledger, hledger's timeclock format is a sub- + set/variant of timeclock.el's. + + hledger's timeclock format was updated in hledger 1.43 and 1.50. If + your old time logs are rejected, you should adapt them to modern + hledger; for now, you can restore the pre-1.43 behaviour with the + --old-timeclock flag. + + Here the timeclock format in hledger 1.50+: + + # Comment lines like these, and blank lines, are ignored: + # comment line + ; comment line + * comment line + + # Lines beginning with b, h, or capital O are also ignored, for compatibility: + b SIMPLEDATE HH:MM[:SS][+-ZZZZ][ TEXT] + h SIMPLEDATE HH:MM[:SS][+-ZZZZ][ TEXT] + O SIMPLEDATE HH:MM[:SS][+-ZZZZ][ TEXT] + + # Lines beginning with i or o are are clock-in / clock-out entries: + i SIMPLEDATE HH:MM[:SS][+-ZZZZ] ACCOUNT[ DESCRIPTION][;COMMENT]] + o SIMPLEDATE HH:MM[:SS][+-ZZZZ][ ACCOUNT][;COMMENT] + + The date is a hledger simple date (YYYY-MM-DD or similar). The time + parts must use two digits. The seconds are optional. A + or - + four-digit time zone is accepted for compatibility, but currently ig- + nored; times are always interpreted as a local time. + + In clock-in entries (i), the account name is required. A transaction + description, separated from the account name by 2+ spaces, is optional. + A transaction comment, beginning with ;, is also optional. (Indented + following comment lines are also allowed, as in journal format.) + + In clock-out entries (o) have no description, but can have a comment if + you wish. A clock-in and clock-out pair form a "transaction" posting + some number of hours to an account - also known as a session. Eg: + + i 2015/03/30 09:00:00 session1 + o 2015/03/30 10:00:00 + + $ hledger -f a.timeclock print + 2015-03-30 * 09:00-10:00 + (session1) 1.00h + + Clock-ins and clock-outs are matched by their account/session name. If + a clock-out does not specify a name, the most recent unclosed clock-in + is closed. You can have multiple sessions active simultaneously. En- + tries are processed in the order they are parsed. Sessions spanning + more than one day are automatically split at day boundaries. + + Eg, the following time log: + + 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 + i 2015/04/02 12:00:00 another:account ; this demonstrates multple sessions being clocked in + i 2015/04/02 13:00:00 some account + o 2015/04/02 14:00:00 + o 2015/04/02 15:00:00 another:account + + generates these transactions: + + $ 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 + + 2015-04-02 * 12:00-15:00 ; this demonstrates multiple sessions being clocked in + (another:account) 3.00h + + 2015-04-02 * 13:00-14:00 + (some account) 1.00h + + 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: + + o use these shell aliases at the command line: + + alias ti='echo i `date "+%Y-%m-%d %H:%M:%S"` $* >>$TIMELOG' + alias to='echo o `date "+%Y-%m-%d %H:%M:%S"` >>$TIMELOG' + + o or Emacs's built-in timeclock.el, or the extended timeclock-x.el, and + perhaps the extras in ledgerutils.el + + o 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. + +Timedot + timedot format is hledger's human-friendly time logging format. Com- + pared to timeclock format, it is more convenient for quick, approxi- + mate, 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 as- + sumed, 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 trans- + action comment following a semicolon. + + After the date line are zero or more time postings, consisting of: + + o An account name - any hledger-style account name, optionally in- + dented. + + o Two or more spaces - required if there is an amount (as in journal + format). + + o A timedot amount, which can be + + o empty (representing zero) + + o 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. + + o 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. + + o Added in 1.32 one or more letters. These are like dots but they + also generate a tag t: (short for "type") with the letter as its + value, and a separate posting for each of the values. This pro- + vides a second dimension of categorisation, viewable in reports + with --pivot t. + + o 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: + + o Blank lines and lines beginning with # or ; are ignored. + + o 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). + + o Before the first date line, lines beginning with * (eg org headings) + are ignored. And from the first date line onward, Emacs org mode + heading prefixes at the start of lines (one or more *'s followed by a + space) will be ignored. This means the time log can also be a org + outline. + + Timedot files don't support directives like journal files. So a common + pattern is to have a main journal file (eg time.journal) that contains + any needed directives, and then includes the timedot file (include + time.timedot). + + 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 + +PART 3: REPORTING CONCEPTS +Time periods + Report start & end date + Most hledger reports will by default show the full time period repre- + sented by the journal. The report start date will be the earliest + transaction or posting date, and the report end date will be the latest + transaction, posting, or market price date. + + Often you will want to see a shorter period, such as the current month. + You can specify a start and/or end date with the -b/--begin, -e/--end, + or -p/--period options, or a date: query argument, described below. + All of these accept the smart date syntax, also described below. + + End dates are exclusive; specify the day after the last day you want to + see in the report. + + When dates are specified by multiple options, the last (right-most) op- + tion wins. And when date: queries and date options are combined, the + report period will be their intersection. + + Examples: + + -b 2016/3/17 + beginning on St. Patrick's day 2016 + + -e 12/1 + ending at the start of December 1st in the current year + + -p 'this month' + during the current month + + -p thismonth + same as above, spaces are optional + + -b 2023 + beginning on the first day of 2023 + + date:2023.. or date:2023- + same as above + + -b 2024 -e 2025 -p '2000 to 2030' date:2020-01 date:2020 : + during January 2020 (the smallest common period, with the -p overriding + -b and -e) + + Smart dates + In hledger's user interfaces (though not in the journal file), you can + optionally use "smart date" syntax. Smart dates can be written with + english words, can be relative, and can have parts omitted. Missing + parts are inferred as 1, when needed. Smart dates can be interpreted + as dates or periods depending on the context. + + Examples: + + 2004-01-01, 2004/10/1, 2004.9.1, 20240504, 2024Q1 : + Exact dates. The year must have at least four digits, the month must + be 1-12, the day must be 1-31, the separator can be - or / or . or + nothing. The q can be upper or lower case and the quarter number must + be 1-4. + + 2004-10 + start of month + + 2004q3 start of third quarter of 2004 + + q3 start of third quarter of current year + + 2004 start of year + + 10/1 or oct or october + October 1st in current year + + 21 21st day in current month + + yesterday, today, tomorrow + -1, 0, 1 days from today + + last/this/next day/week/month/quarter/year + -1, 0, 1 periods from the current period + + in n days/weeks/months/quarters/years + n periods from the current period + + n days/weeks/months/quarters/years ahead + n periods from the current period + + n days/weeks/months/quarters/years ago + -n periods from the current period + + 20181201 + 8 digit YYYYMMDD with valid year month and day + + 201812 6 digit YYYYMM with valid year and month + + Dates with no separators are allowed but might give surprising results + if mistyped: + + o 20181301 (YYYYMMDD with an invalid month) is parsed as an eight-digit + year + + o 20181232 (YYYYMMDD with an invalid day) gives a parse error + + o 201801012 (a valid YYYYMMDD followed by additional digits) gives a + parse error + + The meaning of relative dates depends on today's date. If you need to + test or reproduce old reports, you can use the --today option to over- + ride that. (Except for periodic transaction rules, which are not af- + fected by --today.) + + Report intervals + A report interval can be specified so that reports like register, bal- + ance or activity become multi-period, showing each subperiod as a sepa- + rate row or column. + + The following standard intervals can be enabled with command-line + flags: + + o -D/--daily + + o -W/--weekly + + o -M/--monthly + + o -Q/--quarterly + + o -Y/--yearly + + More complex intervals can be specified using -p/--period, described + below. + + Date adjustments + Start date adjustment + If you let hledger infer a report's start date, it will adjust the date + to the previous natural boundary of the report interval, for convenient + periodic reports. (If you don't want that, specify a start date.) + + For example, if the journal's first transaction is on january 10th, + + o hledger register (no report interval) will start the report on janu- + ary 10th. + + o hledger register --monthly will start the report on the previous + month boundary, january 1st. + + o hledger register --monthly --begin 1/5 will start the report on janu- + ary 5th [1]. + + Also if you are generating transactions or budget goals with periodic + transaction rules, their start date may be adjusted in a similar way + (in certain situations). + + End date adjustment + A report's end date is always adjusted to include a whole number of in- + tervals, so that the last subperiod has the same length as the others. + + For example, if the journal's last transaction is on february 20th, + + o hledger register will end the report on february 20th. + + o hledger register --monthly will end the report at the end of febru- + ary. + + o hledger register --monthly --end 2/14 also will end the report at the + end of february (overriding the requested end date). + + o hledger register --monthly --begin 1/5 --end 2/14 will end the report + on march 4th [1]. + + [1] Since hledger 1.29. + + Period headings + With non-standard subperiods, hledger will show "STARTDATE..ENDDATE" + headings. With standard subperiods (ie, starting on a natural interval + boundary), you'll see more compact headings, which are usually prefer- + able. (Though month names will be in english, currently.) + + So if you are specifying a start date and you want compact headings: + choose a start of year for yearly reports, a start of quarter for quar- + terly reports, a start of month for monthly reports, etc. (Remember, + you can write eg -b 2024 or 1/1 as a shortcut for a start of year, or + 2024-04 or 202404 or Apr for a start of month or quarter.) + + For weekly reports, choose a date that's a Monday. (You can try dif- + ferent dates until you see the short headings, or write eg -b '3 weeks + ago'.) + + Period expressions + The -p/--period option specifies a period expression, which is a com- + pact 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 syn- + onym + -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 "2009/1/1" the first day of 2009; equivalent to "2009/1/1 to + 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 + + 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" + + More complex report intervals + Some more complex intervals can be specified within period expressions, + such as: + + o biweekly (every two weeks) + + o fortnightly + + o bimonthly (every two months) + + o every day|week|month|quarter|year + + o every N days|weeks|months|quarters|years + + Weekly on a custom day: + + o every Nth day of week (th, nd, rd, or st are all accepted after the + number) + + o every WEEKDAYNAME (full or three-letter english weekday name, case + insensitive) + + Monthly on a custom day: + + o every Nth day [of month] (31st day will be adjusted to each month's + last day) + + o every Nth WEEKDAYNAME [of month] + + Yearly on a custom month and day: + + o every MM/DD [of year] (month number and day of month number) + + o every MONTHNAME DDth [of year] (full or three-letter english month + name, case insensitive, and day of month number) + + o 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 week" periods will go from Tue to Tue + -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" + + Multiple weekday intervals + This special form is also supported: + + o every WEEKDAYNAME,WEEKDAYNAME,... (full or three-letter english week- + day 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 weekday" dates will be Mon, Tue, Wed, Thu, Fri; periods will + be Mon, Tue, Wed, Thu, Fri-Sun + -p "every weekend- dates will be Sat, Sun; periods will be Sat, Sun-Fri + day" + +Depth + With the --depth NUM option (short form, usually preferred: -NUM), re- + ports 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. So all of these + are equivalent: depth:2, --depth=2, -2. + + You can also provide custom depths for specific accounts, by providing + a REGEX=NUM argument instead of just NUM (since 1.41). For example, + --depth assets=2 (or depth:assets=2) will collapse accounts matching + the regular expression "assets" to depth 2. So assets:bank:savings + would be collapsed to assets:bank, but liabilities:bank:credit card + would not be affected. + + If REGEX contains spaces or other special characters, enclose it in + quotes in the usual way. Eg: --depth 'credit card=2' + + Combining depth options + If a command line contains multiple general depth options, the last one + wins. (Useful for overriding a depth specified by scripts.) + + Or a command may contain a combination of general and custom depth op- + tions. In this case, the most specifically (deepest) matching option + wins. Some examples: + + o --depth assets=3 --depth expenses=2 --depth 1 would collapse accounts + containing "assets" to depth 3, accounts containing "expenses" to + depth 2, and all other accounts to depth 1. + + o --depth assets=1 --depth savings=2 would collapse assets:bank:savings + to depth 2 (not depth 1; because "savings" matches a deeper part of + the account name than "assets"). + + Note currently, to override a custom depth option --depth REGEX=NUM + with a later option, the later option must use the same REGEX. + +Queries + Many hledger commands accept query arguments, which restrict their + scope and let you report on a precise subset of your data. Here's a + quick overview of hledger's queries: + + o By default, a query argument is treated as a case-insensitive sub- + string pattern for matching account names. Eg: + + dining groceries + car:fuel + o Patterns containing spaces or other special characters must be en- + closed in single or double quotes: + + 'personal care' + o Patterns are actually regular expressions, so you can add regexp + metacharacters for more precision (or you may need to backslash-es- + cape certain characters; see "Regular expressions" above): + + '^expenses\b' + 'food$' + 'fuel|repair' + 'accounts (payable|receivable)' + o To match something other than the account name, you can add a query + type prefix, such as: + + date:202312- + status: + desc:amazon + cur:USD + cur:\\$ + amt:'>0' + acct:groceries (but acct: is the default, so we usually don't bother + writing it) + o To negate a query, add a not: prefix: + + not:status:'*' + not:desc:'opening|closing' + not:cur:USD + o Multiple query terms can be combined, as space-separated queries Eg: + hledger print date:2022 desc:amazon desc:amzn (show transactions + dated in 2022 whose description contains "amazon" or "amzn"). + o Or more flexibly as boolean queries. Eg: hledger print + expr:'date:2022 and (desc:amazon or desc:amzn) and not date:202210' + All hledger commands use the same query language, but different com- + mands may interpret the query in different ways. We haven't described + the commands yet (that's coming in PART 4: COMMANDS below) but here's + the gist of it: + + o Transaction-oriented commands (print, aregister, close, import, de- + scriptions..) try to match transactions (including the transaction's + postings). + + o Posting-oriented commands (register, balance, balancesheet, incomes- + tatement, accounts..) try to match postings. Postings inherit their + transaction's attributes for querying purposes, so transaction fields + like date or description can still be referenced in a posting query. + + o A few commands match in more specific ways. (Eg aregister, which has + a special first argument.) + + Query types + Here are the query types available: + + acct: query + acct:REGEX, or just REGEX + Match account names containing this case insensitive regular expres- + sion. + This is the default query type, so we usually don't bother writing the + "acct:" prefix. + + amt: query + 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.) amt: needs quotes to hide the less + than/greater than sign from the command line shell. + + 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 mag- + nitudes are compared, ignoring sign. + + Keep in mind that amt: matches posting amounts, not account balances. + + code: query + code:REGEX + Match by transaction code (eg check number). + + cur: query + cur:REGEX + Match postings or transactions including any amounts whose cur- + rency/commodity symbol is fully matched by REGEX. (Contrary to + hledger's usual infix matching. To do infix matching, write + .*REGEX.*.) Note, to match special characters which are regex-signifi- + cant, you need to escape them with \. And for characters which are + significant to your shell you will usually need one more level of es- + caping. Eg to match the dollar sign: cur:\\$ or cur:'\$' + + desc: query + desc:REGEX + Match transaction descriptions. + + date: query + date:PERIODEXPR + Match dates (or with the --date2 flag, secondary dates) within the + specified period. PERIODEXPR is a period expression with no report in- + terval. Examples: + date:2016, date:thismonth, date:2/1-2/15, date:2021-07-27..nextquarter. + + date2: query + date2:PERIODEXPR + If you use secondary dates: this matches secondary dates within the + specified period. It is not affected by the --date2 flag. + + depth: query + depth:[REGEXP=]N + Match (or display, depending on command) accounts at or above this + depth, optionally only for accounts matching a provided regular expres- + sion. See Depth for detailed rules. + + note: query + note:REGEX + Match transaction notes (the part of the description right of |, or the + whole description if there's no |). + + payee: query + payee:REGEX + Match transaction payee/payer names (the part of the description left + of |, or the whole description if there's no |). + + real: query + real:, real:0 + Match real or virtual postings respectively. + + status: query + status:, status:!, status:* + Match unmarked, pending, or cleared transactions respectively. + + type: query + type:TYPECODES + Match by account type (see Declaring accounts > Account types). TYPE- + CODES is one or more of the single-letter account type codes ALERXCV, + case insensitive. Note type:A and type:E will also match their respec- + tive subtypes C (Cash) and V (Conversion). Certain kinds of account + alias can disrupt account types, see Rewriting accounts > Aliases and + account types. + + tag: query + tag:NAMEREGEX[=VALREGEX] + Match by tag name, and optionally also by tag value. Note: + + o Both regular expressions do infix matching. If you need a complete + match, use ^ and $. + Eg: tag:'^fullname$', tag:'^fullname$=^fullvalue$ + + o To match values, ignoring names, do tag:.=VALREGEX + + o Accounts also inherit the tags of their parent accounts. + + o Postings also inherit the tags of their account and their transaction + . + + o Transactions also acquire the tags of their postings. + + Negative queries + not: query + not:QUERY + You can prepend not: to a query to negate the match. + Eg: not:equity, not:desc:apple + (Also, a trick: not:not:... can sometimes solve query problems conve- + niently.) + + Space-separated queries + When given multiple space-separated query terms, most commands select + things which match: + + o any of the description terms AND + + o any of the account terms AND + + o any of the status terms AND + + o all the other terms. + + The print command is a little different, showing transactions which: + + o match any of the description terms AND + + o have any postings matching any of the positive account terms AND + + o have no postings matching any of the negative account terms AND + + o match all the other terms. + + Boolean queries + You can write more complicated "boolean" query expressions, enclosed in + quotes and prefixed with expr:. These can combine subqueries with NOT, + AND, OR operators (case insensitive), and parentheses for grouping. + Eg, to show transactions involving both cash and expense accounts: + + hledger print expr:'cash AND expenses' + + The prefix and enclosing quotes are required, so don't write hledger + print cash AND expenses. That would be a space-separated query showing + transactions involving accounts with any of "cash", "and", "expenses" + in their names. + + You can write space-separated queries inside a boolean query, and they + will combine as described above, but it might be confusing and best + avoided. Eg these are equivalent, showing transactions involving cash + or expenses accounts: + + hledger print expr:'cash expenses' + hledger print cash expenses + + There is a restriction with date: queries: they may not be used inside + OR expressions. + + Actually, there are three types of boolean query: expr: for general + use, and any: and all: variants which can be useful with print. + + expr: query + expr:'QUERYEXPR' + For example, expr:'date:lastmonth AND NOT (food OR rent)' means "match + things which are dated in the last month and do not have food or rent + in the account name". + + When using expr: with transaction-oriented commands like print, post- + ing-oriented query terms like acct: and amt: are considered to match + the transaction if they match any of its postings. + So, hledger print expr:'cash and amt:>0' means "show transactions with + (at least one posting involving a cash account) and (at least one post- + ing with a positive amount)". + + any: query + any:'QUERYEXPR' + Like expr:, but when used with transaction-oriented commands like + print, it matches the transaction only if a posting can be matched by + all of QUERYEXPR. + So, hledger print any:'cash and amt:>0' means "show transactions where + at least one posting posts a positive amount to a cash account". + + all: query + all:'QUERYEXPR' + Like expr:, but when used with transaction-oriented commands like + print, it matches the transaction only if all postings are matched by + all of QUERYEXPR (and there is at least one posting). + So, hledger print all:'cash and amt:0' means "show transactions where + all postings involve a cash account and have a zero amount". + Or, hledger print all:'cash or checking' means "show transactions which + touch only cash and/or checking accounts". + + 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. + + Queries and account aliases + When account names are rewritten with --alias or alias, acct: will + match either the old or the new account name. + + Queries and valuation + When amounts are converted to other commodities in cost or value re- + ports, cur: and amt: match the old commodity symbol and the old amount + quantity, not the new ones. (Except in hledger 1.22, #1625.) + +Pivoting + Normally, hledger groups amounts and displays their totals by account + (name). With --pivot PIVOTEXPR, some other field's (or multiple + fields') value is used as a synthetic account name, causing different + grouping and display. PIVOTEXPR can be + + o any of these standard transaction or posting fields (their value is + substituted): status, code, desc, payee, note, acct, comm/cur, amt, + cost + + o or a tag name + + o or any combination of these, colon-separated. + + Some special cases: + + o Colons appearing in PIVOTEXPR or in a pivoted tag value will generate + account hierarchy. + + o When pivoting a posting has multiple values for a tag, the pivoted + value of that tag will be the first value. + + o When a posting has multiple commodities, the pivoted value of + "comm"/"cur" will be "". Also when an unrecognised tag name or field + is provided, its pivoted value will be "". (If this causes confusing + output, consider excluding those postings from the report.) + + Examples: + + 2016/02/16 Yearly Dues Payment + assets:bank account 2 EUR + income:dues -2 EUR ; member: John Doe, kind: Lifetime + + Normal balance report showing account names: + + $ hledger balance + 2 EUR assets:bank account + -2 EUR income:dues + -------------------- + 0 + + Pivoted balance report, using member: tag values instead: + + $ hledger balance --pivot member + 2 EUR + -2 EUR John Doe + -------------------- + 0 + + One way to show only amounts with a member: value (using a query): + + $ hledger balance --pivot member tag:member=. + -2 EUR John Doe + -------------------- + -2 EUR + + Another way (the acct: query matches against the pivoted "account + name"): + + $ hledger balance --pivot member acct:. + -2 EUR John Doe + -------------------- + -2 EUR + + Hierarchical reports can be generated with multiple pivot values: + + $ hledger balance Income:Dues --pivot kind:member + -2 EUR Lifetime:John Doe + -------------------- + -2 EUR + +Generating data + hledger can enrich the data provided to it, or generate new data, in a + number of ways. Mostly, this is done only if you request it: + + o Missing amounts or missing costs in transactions are inferred auto- + matically when possible. + + o The --infer-equity flag infers missing conversion equity postings + from @/@@ costs. + + o The --infer-costs flag infers missing costs from conversion equity + postings. + + o The --infer-market-prices flag infers P price directives from costs. + + o The --auto flag adds extra postings to transactions matched by auto + posting rules. + + o The --forecast option generates transactions from periodic transac- + tion rules. + + o The balance --budget report infers budget goals from periodic trans- + action rules. + + o Commands like close, rewrite, and hledger-interest generate transac- + tions or postings. + + o CSV data is converted to transactions by applying CSV conversion + rules.. etc. + + Such generated data is temporary, existing only at report time. You + can convert it to permanent recorded data by, eg, capturing the output + of hledger print and saving it in your journal file. This can some- + times be useful as a data entry aid. + + If you are curious what data is being generated and why, run hledger + print -x --verbose-tags. -x/--explicit shows inferred amounts and + --verbose-tags adds tags like generated-transaction (from periodic + rules) and generated-posting, modified (from auto posting rules). Sim- + ilar hidden tags (with an underscore prefix) are always present, also, + so you can always match such data with queries like tag:generated or + tag:modified. + +Forecasting + Forecasting, or speculative future reporting, can be useful for esti- + mating 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. + + --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 gen- + erate multiple recurring transactions, so by changing one rule you can + change many forecasted transactions. + + Forecast transactions usually start after ordinary transactions end. + By default, they begin after your latest-dated ordinary transaction, or + today, whichever is later, and they end six months from today. (The + exact rules are a little more complicated, and are given below.) + + This is the "forecast period", which need not be the same as the report + period. You can override it - eg to forecast farther into the future, + or to force forecast transactions to overlap your ordinary transactions + - by giving the --forecast option a period expression argument, like + --forecast=..2099 or --forecast=2023-02-15... Note that the = is re- + quired. + + Inspecting forecast transactions + print is the best command for inspecting and troubleshooting forecast + transactions. Eg: + + ~ monthly from 2022-12-20 rent + assets:bank:checking + expenses:rent $1000 + + $ hledger print --forecast --today=2023/4/21 + 2023-05-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + + 2023-06-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + + 2023-07-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + + 2023-08-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + + 2023-09-20 rent + ; generated-transaction: ~ monthly from 2022-12-20 + assets:bank:checking + expenses:rent $1000 + + Here there are no ordinary transactions, so the forecasted transactions + begin on the first occurrence after today's date. (You won't normally + use --today; it's just to make these examples reproducible.) + + 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 + + Forecast tags + Forecast transactions generated by --forecast have a hidden tag, _gen- + erated-transaction. So if you ever need to match forecast transac- + tions, you could use tag:_generated-transaction (or just tag:generated) + in a query. + + For troubleshooting, you can add the --verbose-tags flag. Then, visi- + ble generated-transaction tags will be added also, so you can view them + with the print command. Their value indicates which periodic rule was + responsible. + + Forecast period, in detail + Forecast start/end dates are chosen so as to do something useful by de- + fault in almost all situations, while also being flexible. Here are + (with luck) the exact rules, to help with troubleshooting: + + The forecast period starts on: + + o the later of + + o the start date in the periodic transaction rule + + o the start date in --forecast's argument + + o otherwise (if those are not available): the later of + + o the report start date specified with -b/-p/date: + + o the day after the latest ordinary transaction in the journal + + o otherwise (if none of these are available): today. + + The forecast period ends on: + + o the earlier of + + o the end date in the periodic transaction rule + + o the end date in --forecast's argument + + o otherwise: the report end date specified with -e/-p/date: + + o otherwise: 180 days (~6 months) from today. + + Forecast troubleshooting + When --forecast is not doing what you expect, one of these tips should + help: + + o Remember to use the --forecast option. + + o Remember to have at least one periodic transaction rule in your jour- + nal. + + o Test with print --forecast. + + o Check for typos or too-restrictive start/end dates in your periodic + transaction rule. + + o Leave at least 2 spaces between the rule's period expression and de- + scription fields. + + o Check for future-dated ordinary transactions suppressing forecasted + transactions. + + o Try setting explicit report start and/or end dates with -b, -e, -p or + date: + + o Try adding the -E flag to encourage display of empty periods/zero + transactions. + + o Try setting explicit forecast start and/or end dates with --fore- + cast=START..END + + o Consult Forecast period, in detail, above. + + o Check inside the engine: add --debug=2 (eg). + +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. + +Amount formatting + 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 preci- + sions, and bring other benefits such as error checking for commodity + symbols. Here's an example: + + # Set display styles (and decimal marks, for parsing, if there is no decimal-mark directive) + # for the $, EUR, INR and no-symbol commodities: + commodity $1,000.00 + commodity EUR 1.000,00 + commodity INR 9,99,99,999.00 + commodity 1 000 000.9455 + + But for convenience, if a commodity directive is not present, hledger + infers a commodity's display styles from its amounts as they are writ- + ten in the journal (excluding cost amounts and amounts in periodic + transaction rules or auto posting rules). It uses + + o the symbol placement and decimal mark of the first amount seen + + o the digit group marks of the first amount with digit group marks + + o and the maximum number of decimal digits seen across all amounts. + + And as fallback if no applicable amounts are found, it would use a de- + fault 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. + + 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 deci- + mal digits appears as "0". + + Trailing decimal marks + If you're wondering why your print report sometimes shows trailing dec- + imal marks, with no decimal digits; it does this when showing amounts + that have digit group marks but no decimal digits, to disambiguate them + and allow them to be re-parsed reliably (see Decimal marks). Eg: + + commodity $1,000.00 + + 2023-01-02 + (a) $1000 + + $ hledger print + 2023-01-02 + (a) $1,000. + + If this is a problem (eg when exporting to Ledger), you can avoid it by + disabling digit group marks, eg with -c/--commodity (for each affected + commodity): + + $ hledger print -c '$1000.00' + 2023-01-02 + (a) $1000 + + or by forcing print to always show decimal digits, with --round: + + $ hledger print -c '$1,000.00' --round=soft + 2023-01-02 + (a) $1,000.00 + + Amount parseability + More generally, hledger output falls into three rough categories, which + format amounts a little bit differently to suit different consumers: + + 1. "hledger-readable output" - should be readable by hledger (and by + humans) + + o This is produced by reports that show full journal entries: print, + import, close, rewrite etc. + + o It shows amounts with their original journal precisions, which may + not be consistent from one amount to the next. + + o It adds a trailing decimal mark when needed to avoid showing ambigu- + ous amounts. + + o It can be parsed reliably (by hledger and ledger2beancount at least, + but perhaps not by Ledger..) + + 2. "human-readable output" - usually for humans + + o This is produced by all other reports. + + o It shows amounts with standard display precisions, which will be con- + sistent within each commodity. + + o It shows ambiguous amounts unmodified. + + o 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 sin- + gle mark is a digit group mark). + + 3. "machine-readable output" - usually for other software + + o This is produced by all reports when an output format like csv, tsv, + json, or sql is selected. + + o It shows amounts as 1 or 2 do, but without digit group marks. + + o It can be parsed reliably (if needed, the decimal mark can be changed + with -c/--commodity-style). + +Cost reporting + In some transactions - for example a currency conversion, or a purchase + or sale of stock - one commodity is exchanged for another. In these + transactions there is a conversion rate, also called the cost (when + buying) or selling price (when selling). (In hledger docs we just say + "cost" generically for convenience.) With the -B/--cost flag, hledger + can show amounts "at cost", converted to the cost's commodity. + + 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: + + o It sacrifices some error checking. For example, if you accidentally + wrote 10 instead of 100, hledger would not be able to detect the mis- + take. + + o It is sensitive to the order of postings - if they were reversed, a + different entry would be inferred and reports would be different. + + o 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. + + 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 out- + put). Ie they will be displayed "at cost" or "at sale price". + + Some things to note: + + o Costs are attached to specific posting amounts in specific transac- + tions, and once recorded they do not change. This contrasts with + market prices, which are ambient and fluctuating. + + o Conversion to cost is performed before conversion to market value + (described below). + + 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: + + o The per-unit cost basis is not easy to read. + + o Instead of -B you must remember to type -B --infer-costs. + + o --infer-costs works only where hledger can identify the two eq- + uity:conversion postings and match them up with the two non-equity + postings. So writing the journal entry in a particular format be- + comes more important. More on this below. + + Inferring equity conversion postings + Can we go in the other direction ? Yes, if you have transactions writ- + ten 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 "eq- + uity:conversion:A-B:B" where A is the alphabetically first commodity + symbol. You can customise the "equity:conversion" part by declaring an + account with the V/Conversion account type. + + Note you will need to add account declarations for these to your jour- + nal, if you use check accounts or check --strict. + + 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 - preserv- + ing 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: + + o 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. + + o The add command does not yet accept this kind of entry (#2056). + + o This is the most verbose form. + + 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: + + o Two non-equity postings, in different commodities. Their order is + significant: the cost will be added to the first of them. + + o 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 conver- + sion posting's amount. Equity conversion accounts are: + + o any accounts declared with account type V/Conversion, or their sub- + accounts + + o otherwise, accounts named equity:conversion, equity:trade, or eq- + uity: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. + + 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. + +Value reporting + hledger can also show amounts "at market value", converted to some + other commodity using the market price or conversion rate on a certain + date. + + This is controlled by the --value=TYPE[,COMMODITY] option. We also + provide simpler -V and -X COMMODITY aliases for this, which are often + sufficient. The market prices are declared with a special P directive, + and/or they can be inferred from the costs recorded in transactions, by + using the --infer-market-prices flag. + + -X: Value in specified commodity + The -X COMM (or --exchange=COMM) option converts amounts to their mar- + ket value in the specified commodity, using the market prices in effect + on the valuation date(s), if any. (More on these in a minute.) + + Use this when you want to (eg) show everything in your base currency as + far as possible. (Commodities for which no conversion rate can be + found, will not be converted.) + + COMM should be the full commodity symbol or name. Remember to quote + special shell characters, if needed. Some examples: + + o -X + + o -X$ (nothing after $, no quoting needed) + + o -X CNY (the space after -X is optional) + + o -X 'red apples' + + o -X 'r&r' + + -V: Value in default commodity(s) + The -V/--market flag is a variant of -X where you don't have to specify + COMM. Instead it tries to guess a default valuation commodity for each + original commodity, based on the market prices in effect on the valua- + tion date(s). + + -V can often be a convenient shortcut for -X MYCURRENCY, but not al- + ways; depending on your data it could guess multiple valuation commodi- + ties. Usually you want to convert to a single commodity, so it's bet- + ter to use -X, unless you're sure -V is doing what you want. + + 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: + + o For single period reports (including normal print and register re- + ports): + + o If an explicit report end date is specified, that is used. + + o Otherwise the latest transaction date or non-future P directive + date is used. + + o 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. + + 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 direc- + tive, 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 com- + bining 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 con- + verted. + + --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 confus- + ing/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: + + o multicommodity transactions with explicit prices (@/@@) + + o multicommodity transactions with implicit prices (no @, two commodi- + ties, unbalanced). (With these, the order of postings matters. + hledger print -x can be useful for troubleshooting.) + + o 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: + + o -X EUR --infer-market-prices, not -V --infer-market-prices + + o --value=then,EUR --infer-market-prices, not --value=then --infer-mar- + ket-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 + + 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 suit- + able 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: + + o If you have P directives, they determine which commodities -V will + convert, and to what. + + o 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 con- + verted. + + --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 commod- + ity, using market prices on each posting's date. + + --value=end + Convert amounts to their value in the default valuation commod- + ity, 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 commod- + ity using current market prices (as of when report is gener- + ated). + + --value=YYYY-MM-DD + Convert amounts to their value in the default valuation commod- + ity 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. + + Valuation examples + Here are some quick examples of -V: + + ; one euro is worth this many dollars from nov 1 + P 2016/11/01 $1.10 + + ; purchase some euros on nov 3 + 2016/11/3 + assets:euros 100 + assets:checking + + ; the euro is worth fewer dollars by dec 21 + P 2016/12/21 $1.03 + + How many euros do I have ? + + $ hledger -f t.j bal -N euros + 100 assets:euros + + What are they worth at end of nov 3 ? + + $ hledger -f t.j bal -N euros -V -e 2016/11/4 + $110.00 assets:euros + + What are they worth after 2016/12/21 ? (no report end date specified, + defaults to today) + + $ hledger -f t.j bal -N euros -V + $103.00 assets:euros + + Here are some examples showing the effect of --value, as seen with + print: + + P 2000-01-01 A 1 B + P 2000-02-01 A 2 B + P 2000-03-01 A 3 B + P 2000-04-01 A 4 B + + 2000-01-01 + (a) 1 A @ 5 B + + 2000-02-01 + (a) 1 A @ 6 B + + 2000-03-01 + (a) 1 A @ 7 B + + Show the cost of each posting: + + $ hledger -f- print --cost + 2000-01-01 + (a) 5 B + + 2000-02-01 + (a) 6 B + + 2000-03-01 + (a) 7 B + + Show the value as of the last day of the report period (2000-02-29): + + $ hledger -f- print --value=end date:2000/01-2000/03 + 2000-01-01 + (a) 2 B + + 2000-02-01 + (a) 2 B + + With no report period specified, the latest transaction date or price + date is used as valuation date (2000-04-01): + + $ hledger -f- print --value=end + 2000-01-01 + (a) 3 B + + 2000-02-01 + (a) 3 B + + 2000-03-01 + (a) 3 B + + The value today is the same (the 2000-04-01 price is still in effect): + + $ 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 + + Interaction of valuation and queries + When matching postings based on queries in the presence of valuation, + the following happens: + + 1. The query is separated into two parts: + + 1. the currency (cur:) or amount (amt:). + + 2. all other parts. + + 2. The postings are matched to the currency and amount queries based on + pre-valued amounts. + + 3. Valuation is applied to the postings. + + 4. The postings are matched to the other parts of the query based on + post-valued amounts. + + Related: #1625 + + Effect of valuation on reports + Here is a reference for how valuation is supposed to affect each part + of hledger's reports. It may be useful when troubleshooting. If you + find problems, please report them, ideally with a reproducible example. + Related: #329, #1083. + + First, a quick glossary: + + cost calculated using price(s) recorded in the transaction(s). + + value market value using available market price declarations, or the + unchanged amount if no conversion rate can be found. + + report start + the first day of the report period specified with -b or -p or + date:, otherwise today. + + report or journal start + the first day of the report period specified with -b or -p or + date:, otherwise the earliest transaction date in the journal, + otherwise today. + + report end + the last day of the report period specified with -e or -p or + date:, otherwise today. + + report or journal end + the last day of the report period specified with -e or -p or + date:, otherwise the latest transaction date in the journal, + otherwise today. + + report interval + a flag (-D/-W/-M/-Q/-Y) or period expression that activates the + report's multi-period mode (whether showing one or many subperi- + ods). + + Report -B, --cost -V, -X --value=then --value=end --value=DATE, + type --value=now + -------------------------------------------------------------------------------------------- + print + posting cost value at re- value at posting value at re- value at + amounts port end or date port or DATE/today + today journal end + balance unchanged unchanged unchanged unchanged unchanged + asser- + tions/as- + signments + + register + starting cost value at re- valued at day value at re- value at + balance port or each historical port or DATE/today + (-H) journal end posting was made journal end + starting cost value at day valued at day value at day value at + balance before re- each historical before re- DATE/today + (-H) with port or posting was made port or + report journal journal + interval start start + posting cost value at re- value at posting value at re- value at + amounts port or date port or DATE/today + journal end journal end + summary summarised value at pe- sum of postings value at pe- value at + posting cost riod ends in interval, val- riod ends DATE/today + amounts ued at interval + with re- start + port in- + terval + running sum/average sum/average sum/average of sum/average sum/average + total/av- of displayed of displayed displayed values of displayed of displayed + erage values values values values + + balance + (bs, bse, + cf, is) + balance sums of value at re- value at posting value at re- value at + changes costs port end or date port or DATE/today of + today of journal end sums of post- + sums of of sums of ings + postings postings + budget like balance like balance like balance like bal- like balance + amounts changes changes changes ances changes + (--bud- + get) + grand to- sum of dis- sum of dis- sum of displayed sum of dis- sum of dis- + tal played val- played val- valued played val- played values + ues ues ues + + balance + (bs, bse, + cf, is) + with re- + port in- + terval + starting sums of value at re- sums of values of value at re- sums of post- + balances costs of port start postings before port start ings before + (-H) postings be- of sums of report start at of sums of report start + fore report all postings respective post- all postings + start before re- ing dates before re- + port start port start + balance sums of same as sums of values of balance value at + changes costs of --value=end postings in pe- change in DATE/today of + (bal, is, postings in riod at respec- each period, sums of post- + bs period tive posting valued at ings + --change, dates period ends + cf + --change) + end bal- sums of same as sums of values of period end value at + ances costs of --value=end postings from be- balances, DATE/today of + (bal -H, postings fore period start valued at sums of post- + is --H, from before to period end at period ends ings + bs, cf) report start respective post- + to period ing dates + end + budget like balance like balance like balance like bal- like balance + amounts changes/end changes/end changes/end bal- ances changes/end + (--bud- balances balances ances balances + get) + row to- sums, aver- sums, aver- sums, averages of sums, aver- sums, aver- + tals, row ages of dis- ages of dis- displayed values ages of dis- ages of dis- + averages played val- played val- played val- played values + (-T, -A) ues ues ues + column sums of dis- sums of dis- sums of displayed sums of dis- sums of dis- + totals played val- played val- values played val- played values + ues ues ues + grand to- sum, average sum, average sum, average of sum, average sum, average + tal, of column of column column totals of column of column to- + grand av- totals totals totals tals + erage + + + --cumulative is omitted to save space, it works like -H but with a zero + starting balance. + +PART 4: COMMANDS + Here are hledger's standard subcommands. You can list these by running + hledger. If you have installed more add-on commands, they also will be + listed. + + In the following command docs, each command's specific options are + shown. Most commands also support the general options described above, + though some of them might have no effect. (Usually if there's a sensi- + ble way for a general option to affect a command, it will.) You can + list all of a command's options by running hledger CMD -h. + + Help commands + + o commands - show the hledger commands list (default) + + o demo - show small hledger demos in the terminal + + o help - show the hledger manual with info, man, or pager + + User interface commands + + o repl - run commands from an interactive prompt + + o run - run commands from a script + + o ui - (if installed) run hledger's terminal UI + + o web - (if installed) run hledger's web UI + + Data entry commands + + o add - add transactions using terminal prompts + + o import - add new transactions from other files, eg CSV files + + Basic report commands + + o accounts - show account names + + o codes - show transaction codes + + o commodities - show commodity/currency symbols + + o descriptions - show transaction descriptions + + o files - show input file paths + + o notes - show note parts of transaction descriptions + + o payees - show payee parts of transaction descriptions + + o prices - show market prices + + o stats - show journal statistics + + o tags - show tag names + + Standard report commands + + o print - show transactions or export journal data + + o aregister (areg) - show transactions in a particular account + + o register (reg) - show postings in one or more accounts & running to- + tal + + o balancesheet (bs) - show assets, liabilities and net worth + + o balancesheetequity (bse) - show assets, liabilities and equity + + o cashflow (cf) - show changes in liquid assets + + o incomestatement (is) - show revenues and expenses + + Advanced report commands + + o balance (bal) - show balance changes, end balances, budgets, gains.. + + o roi - show return on investments + + Chart commands + + o activity - show bar charts of posting counts per period + + Data generation commands + + o close - generate balance-zeroing/restoring transactions + + o rewrite - generate auto postings, like print --auto + + Maintenance commands + + o check - check for various kinds of error in the data + + o diff - compare account transactions in two journal files + + o setup - check and show the status of the hledger installation + + o test - run self tests + + Next, these commands are described in detail. + +Help commands + commands + Show the hledger commands list. + + Flags: + --builtin show only builtin commands, not addons + + demo + Play demos of hledger usage in the terminal, if asciinema is installed. + + Flags: + -s --speed=SPEED playback speed (1 is original speed, .5 is half, 2 + is double, etc (default: 2)) + + Run this command with no argument to list the demos. To play a demo, + write its number or a prefix or substring of its title. Tips: + + Make your terminal window large enough to see the demo clearly. + + Use the -s/--speed SPEED option to set your preferred playback speed, + eg -s4 to play at 4x original speed or -s.5 to play at half speed. The + default speed is 2x. + + During playback, several keys are available: SPACE to pause/unpause, . + to step forward (while paused), CTRL-c quit. + + Examples: + + $ hledger demo # list available demos + $ hledger demo 1 # play the first demo at default speed (2x) + $ hledger demo install -s4 # play the "install" demo at 4x speed + + This command is experimental: there aren't many useful demos yet. + + help + Show the hledger user manual with info, man, or a pager. With a (case + insensitive) TOPIC argument, try to open it at that section heading. + + Flags: + -i show the manual with info + -m show the manual with man + -p show the manual with $PAGER or less + (less is always used if TOPIC is specified) + + This command shows the hledger manual built in to your hledger exe- + cutable. It can be useful when offline, or when you prefer the termi- + nal to a web browser, or when the appropriate hledger manual or viewers + are not installed properly on your system. + + By default it chooses the best viewer found in $PATH, trying in this + order: info, man, $PAGER, less, more, stdout. (If a TOPIC is speci- + fied, $PAGER and more are not tried.) You can force the use of info, + man, or a pager with the -i, -m, or -p flags. If no viewer can be + found, or if running non-interactively, it just prints the manual to + stdout. + + When using info, TOPIC can match either the full heading or a prefix. + If your info --version is < 6, you'll need to upgrade it, eg with 'brew + install texinfo' on mac. + + When using man or less, TOPIC must match the full heading. For a pre- + fix match, you can write 'TOPIC.*'. + + Examples + + $ hledger help -h # show the help command's usage + $ hledger help # show the manual with info, man or $PAGER + $ hledger help 'time periods' # show the manual's "Time periods" topic + $ hledger help 'time periods' -m # use man, even if info is installed + +User interface commands + repl + Start an interactive prompt, where you can run any of hledger's com- + mands. Data files are parsed just once, so the commands run faster. + + Flags: + no command-specific flags + + This command is experimental and could change in the future. + + hledger repl starts a read-eval-print loop (REPL) where you can enter + commands interactively. As with the run command, each input file (or + each input file/input options combination) is parsed just once, so com- + mands will run more quickly than if you ran them individually at the + command line. + + Also like run, the input file(s) specified for the repl command will be + the default input for all interactive commands. You can override this + temporarily by specifying an -f option in particular commands. But + note that commands will not see any changes made to input files (eg by + add) until you exit and restart the REPL. + + The command syntax is the same as with run: + + o enter one hledger command at a time, without the usual hledger first + word + + o empty lines and comment text from # to end of line are ignored + + o use single or double quotes to quote arguments when needed + + o type exit or quit or control-D to exit the REPL. + + While it is running, the REPL remembers your command history, and you + can navigate in the usual ways: + + o Keypad or Emacs navigation keys to edit the current command line + + o UP/DOWN or control-P/control-N to step back/forward through history + + o control-R to search for a past command + + o TAB to complete file paths. + + Generally repl command lines should feel much like the normal hledger + CLI, but you may find differences. repl is a little stricter; eg it + requires full command names or official abbreviations (as seen in the + commands list). + + The commands and help commands, and the command help flags (CMD --tldr, + CMD -h/--help, CMD --info, CMD --man), can be useful. + + You can type control-C to cancel a long-running command (but only once; + typing it a second time will exit the REPL). + + And in most shells you can type control-Z to temporarily exit to the + shell (and then fg to return to the REPL). + + Examples + Start the REPL and enter some commands: + + $ hledger repl + Enter hledger commands. To exit, enter 'quit' or 'exit', or send EOF. + % stats + Main file : .../2025.journal + ... + % stats -f 2024/2024.journal + Main file : .../2024.journal + ... + % stats + Main file : .../2025.journal + ... + + or: + + $ hledger repl -f some.journal + Enter hledger commands. To exit, enter 'quit' or 'exit', or send EOF. + % bs + ... + % print -b 'last week' + ... + % bs -f other.journal + ... + + run + Run a sequence of hledger commands, provided as files or command line + arguments. Data files are parsed just once, so the commands run + faster. + + Flags: + no command-specific flags + + This command is experimental and could change in the future. + + You can use run in three ways: + + o hledger run -- CMD1 -- CMD2 -- CMD3 - read commands from the command + line, separated by -- + + o hledger run SCRIPTFILE1 SCRIPTFILE2 - read commands from one or more + files + + o cat SCRIPTFILE1 | hledger run - read commands from standard input. + + run first loads the input file(s) specified by LEDGER_FILE or by -f op- + tions, in the usual way. Then it runs each command in turn, each using + the same input data. But if you want a particular command to use dif- + ferent input, you can specify an -f option within that command. This + will override (not add to) the default input, just for that command. + + Each input file (more precisely, each combination of input file and in- + put options) is parsed only once. This means that commands will not + see any changes made to these files, until the next run. But the com- + mands will run more quickly than if run individually (typically about + twice as fast). + + Command scripts, whether in a file or written on the command line, have + a simple syntax: + + o each line may contain a single hledger command and its arguments, + without the usual hledger first word + + o empty lines are ignored + + o text from # to end of line is a comment, and ignored + + o you can use single or double quotes to quote arguments when needed, + as on the command line + + o these extra commands are available: echo TEXT prints some text, and + exit or quit ends the run. + + On unix systems you can use #!/usr/bin/env hledger run in the first + line of a command file to make it a runnable script. If that gives an + error, use #!/usr/bin/env -S hledger run. + + It's ok to use the run command recursively within a command script. + + You may find some differences in behaviour between run command lines + and normal hledger command lines. run is a little stricter; eg it re- + quires full command names or official abbreviations (as seen in the + commands list), and command options must be written after the command + name. + + Examples + Run commands from the command line: + + hledger -f some.journal run -- balance assets --depth 2 -- balance liabilities -f /some/other.journal --depth 3 --transpose -- stats + + This would load some.journal, run balance assets --depth 2 on it, then + run balance liabilities --depth 3 --transpose on /some/other.journal, + and finally run stats on some.journal + + Run commands from standard input: + + (echo "files"; echo "stats") | hledger -f some.journal run + + Run commands as a script: + + $ cat report + #!/usr/bin/env -S hledger run -f some.journal + + echo "List of accounts in some.journal" + accounts + + echo "Assets of some.journal" + balance assets --depth 2 + + echo "Liabilities from /some/other.journal" + balance liabilities -f /some/other.journal --depth 3 --transpose + + echo "Commands from another.script, applied to another.journal" + run -f another.journal another.script + + $ chmod +x report + $ ./report + List of accounts in some.journal + ... + + ui + Runs hledger-ui (if installed). + + web + Runs hledger-web (if installed). + +Data entry commands + add + Add new transactions to a journal file, with interactive prompting. + + Flags: + --no-new-accounts don't allow creating new accounts + + Many hledger users edit their journals directly with a text editor, or + generate them from CSV. For more interactive data entry, there is the + add command, which prompts interactively on the console for new trans- + actions, 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: + + o add tries to provide useful defaults, using the most similar (by de- + scription) recent transaction (filtered by the query, if any) as a + template. + + o You can also set the initial defaults with command line arguments. + + o Readline-style edit keys can be used during data entry. + + o The tab key will auto-complete whenever possible - accounts, pay- + ees/descriptions, dates (yesterday, today, tomorrow). If the input + area is empty, it will insert the default value. + + o A parenthesised transaction code may be entered following a date. + + o Comments and tags may be entered following a description or amount. + + o If you make a mistake, enter < at any prompt to go one step backward. + + o Input prompts are displayed in a different colour when the terminal + supports it. + + Notes: + + o If you enter a number with no commodity symbol, and you have declared + a default commodity with a D directive, you might expect add to add + this symbol for you. It does not do this; we assume that if you are + using a D directive you prefer not to see the commodity symbol re- + peated on amounts in the journal. + + o add creates entries in journal format; it won't work with timeclock + or timedot files. + + Examples: + + o Record new transactions, saving to the default journal file: + + hledger add + + o Add transactions to 2024.journal, but also load 2023.journal for com- + pletions: + + hledger add --file 2024.journal --file 2023.journal + + o Provide answers for the first four prompts: + + hledger add today 'best buy' expenses:supplies '$20' + + There is a detailed tutorial at https://hledger.org/add.html. + + add and balance assertions + Since hledger 1.43, you can add a balance assertion by writing AMOUNT = + BALANCE when asked for an amount. Eg 100 = 500. + + Also, each time you enter a new amount, hledger re-checks all balance + assertions in the journal and rejects the new amount if it would make + any of them fail. You can run add with -I/--ignore-assertions to dis- + able balance assertion checking. + + add and balance assignments + Since hledger 1.50.3, you can add a balance assignment by writing = + BALANCE (or ==, =* etc) when asked for an amount. The missing amount + will be calculated automatically. + + add normally won't let you add a new posting which is dated earlier + than an existing balance assignment. (Because when add runs, existing + balance assignments have already been calculated and converted to + amounts and balance assertions.) You can allow it by disabling balance + assertion checking with -I. + + import + Import new transactions from one or more data files to the main jour- + nal. + + Flags: + --catchup just mark all transactions as already imported + --dry-run just show the transactions to be imported + + This command detects new transactions in one or more data files speci- + fied as arguments, and appends them to the main journal. + + You can import from any input file format hledger supports, but + CSV/SSV/TSV files, downloaded from financial institutions, are the most + common import source. + + The import destination is the default journal file, or another speci- + fied in the usual way with $LEDGER_FILE or -f/--file. It should be in + journal format. + + Examples: + + $ hledger import bank1-checking.csv bank1-savings.csv + + $ hledger import *.csv + + Import dry run + It's useful to preview the import by running first with --dry-run, to + sanity check the range of dates being imported, and to check the effect + of your conversion rules if converting from CSV. Eg: + + $ hledger import bank.csv --dry-run + + The dry run output is valid journal format, so hledger can re-parse it. + If the output is large, you could show just the uncategorised transac- + tions like so: + + $ hledger import --dry-run bank.csv | hledger -f- -I print unknown + + You could also run this repeatedly to see the effect of edits to your + conversion rules: + + $ watchexec -- "hledger import --dry-run bank.csv | hledger -f- -I print unknown" + + Once the conversion and dates look good enough to import to your jour- + nal, perhaps with some manual fixups to follow, you would do the actual + import: + + $ hledger import bank.csv + + Overlap detection + Reading CSV files is built in to hledger, and not specific to import; + so you could also import by doing hledger -f bank.csv print + >>$LEDGER_FILE. + + But import is easier and provides some advantages. The main one is + that it avoids re-importing transactions it has seen on previous runs. + This means you don't have to worry about overlapping data in successive + downloads of your bank CSV; just download and import as often as you + like, and only the new transactions will be imported each time. + + We don't call this "deduplication", as it's generally not possible to + reliably detect duplicates in bank CSV. Instead, import remembers the + latest date processed previously in each CSV file (saving it in a hid- + den file), and skips any records prior to that date. This works well + for most real-world CSV, where: + + 1. the data file name is stable (does not change) across imports + + 2. the item dates are stable across imports + + 3. the order of same-date items is stable across imports + + 4. the newest items have the newest dates + + (Occasional violations of 2-4 are often harmless; you can reduce the + chance of disruption by downloading and importing more often.) + + Overlap detection is automatic, and shouldn't require much attention + from you, except perhaps at first import (see below). But here's how + it works: + + o For each FILE being imported from: + + 1. hledger reads a file named .latest.FILE file in the same direc- + tory, if any. This file contains the latest record date previ- + ously imported from FILE, in YYYY-MM-DD format. If multiple + records with that date were imported, the date is repeated on N + lines. + + 2. hledger reads records from FILE. If a latest date was found in + step 1, any records before that date, and the first N records on + that date, are skipped. + + o After a successful import from all FILEs, without error and without + --dry-run, hledger updates each FILE's .latest.FILE for next time. + + If this goes wrong, it's relatively easy to repair: + + o You'll notice it before import when you preview with import + --dry-run. + + o Or after import when you try to reconcile your hledger account bal- + ances with your bank. + + o hledger print -f FILE.csv will show all recently downloaded transac- + tions. Compare these with your journal. Copy/paste if needed. + + o Update your conversion rules and print again, if needed. + + o You can manually update or remove the .latest file, or use import + --catchup FILE. + + o Download and import more often, eg twice a week, at least while you + are learning. It's easier to review and troubleshoot when there are + fewer transactions. + + First import + The first time you import from a file, when no corresponding .latest + file has been created yet, all of the records will be imported. + + But perhaps you have been entering the data manually, so you know that + all of these transactions are already recorded in the journal. In this + case you can run hledger import --catchup once. This will create a + .latest file containing the latest CSV record date, so that none of + those records will be re-imported. + + Or, if you know that some but not all of the transactions are in the + journal, you can create the .latest file yourself. Eg, let's say you + previously recorded foobank transactions up to 2024-10-31 in the jour- + nal. Then in the directory where you'll be saving foobank.csv, you + would create a .latest.foobank.csv file containing + + 2024-10-31 + + Or if you had three foobank transactions recorded with that date, you + would repeat the date that many times: + + 2024-10-31 + 2024-10-31 + 2024-10-31 + + Then hledger import foobank.csv [--dry-run] will import only the newer + records. + + Importing balance assignments + Journal entries added by import will have all posting amounts made ex- + plicit (like print -x). + + This means that any balance assignments in the imported entries would + need to be evaluated. But this generally isn't possible, as the main + file's account balances are not visible during import. So try to avoid + generating balance assignments with your CSV rules, or importing from a + journal that contains balance assignments. (Balance assignments are + best avoided anyway.) + + But if you must use them, eg because your CSV includes only balances: + you can import with print, which leaves implicit amounts implicit. + (print can also do overlap detection like import, with the --new flag): + + $ hledger print --new -f bank.csv >> $LEDGER_FILE + + (If you think import should preserve implicit balances, please test + that and send a pull request.) + + Import and commodity styles + Amounts in entries added by import will be formatted according to the + journal's canonical commodity styles, as declared by commodity direc- + tives or inferred from the journal's amounts. + + Related: CSV > Amount decimal places. + + Import archiving + When importing from a CSV rules file (hledger import bank.rules), you + can use the archive rule to enable automatic archiving of the data + file. After a successful import, the data file (specified by source) + will be moved to an archive folder (data/, next to the rules file, + auto-created), and renamed similar to the rules file, with a date. + This can be useful for troubleshooting, detecting variations in your + banks' CSV data, regenerating entries with improved rules, etc. + + The archive rule also causes import to handle source glob patterns dif- + ferently: when there are multiple matched files, it will pick the old- + est, not the newest. + + Import special cases + Deduplication + Here are two kinds of "deduplication" which import does not handle (and + should not, because these can happen legitimately in financial data): + + o Two or more of the new CSV records are identical, and generate iden- + tical new journal entries. + + o A new CSV record generates a journal entry identical to one(s) al- + ready in the journal. + + Varying file name + If you have a download whose file name varies, you could rename it to a + fixed name after each download. Or you could use a CSV source rule + with a suitable glob pattern, and import from the .rules file. + + Multiple versions + Say you download bank.csv, import it, but forget to delete it from your + downloads folder. The next time you download it, your web browser will + save it as (eg) bank (2).csv. The source rule's glob patterns are for + just this situation: instead of specifying source bank.csv, specify + source bank*.csv. Then hledger -f bank.rules CMD or hledger import + bank.rules will automatically pick the newest matched file (bank + (2).csv). + + Alternately, what if you download, but forget to import or delete, then + download again ? Now each of bank.csv and bank (2).csv might contain + data that's not in the other, and not in your journal. In this case, + it's best to import each of them in turn, oldest first (otherwise, + overlap detection could cause new records to be skipped). Enabling im- + port archiving ensures this. Then hledger import bank.rules; hledger + import bank.rules will import and archive first bank.csv, then bank + (2).csv. + +Basic report commands + accounts + List the account names used or declared in the journal. + + Flags: + -u --used list accounts used + -d --declared list accounts declared + --undeclared list accounts used but not declared + --unused list accounts declared but not used + --find list the first account matched by the first + argument (a case-insensitive infix regexp) + --types also show account types when known + --positions also show where accounts were declared + --directives show as account directives, for use in journals + -l --flat list/tree mode: show accounts as a flat list + (default) + -t --tree list/tree mode: show accounts as a tree + --drop=N flat mode: omit N leading account name parts + + This command lists account names - all of them by default. or just the + ones which have been used in transactions, or declared with account di- + rectives, or used but not declared, or declared but not used, or just + the first account name matched by a pattern. + + You can add query arguments to select a subset of transactions or ac- + counts. + + 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 ac- + count's declaration, if any, and the account's overall declaration or- + der; these may be useful when troubleshooting account display order. + + With --directives, it shows valid account directives which could be + pasted into a journal file. This is useful together with --undeclared + when updating your account declarations to satisfy hledger check ac- + counts. + + 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 alphanumeri- + cally-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 + + codes + List the codes seen in transactions, in the order parsed. + + Flags: + no command-specific flags + + This command prints the value of each transaction's code field, in the + order transactions were parsed. The transaction code is an optional + value written in parentheses between the date and description, often + used to store a cheque number, order number or similar. + + Transactions aren't required to have a code, and missing or empty codes + will not be shown by default. With the -E/--empty flag, they will be + printed as blank lines. + + You can add a query to select a subset of transactions. + + Examples: + + 2022/1/1 (123) Supermarket + Food $5.00 + Checking + + 2022/1/2 (124) Post Office + Postage $8.32 + Checking + + 2022/1/3 Supermarket + Food $11.23 + Checking + + 2022/1/4 (126) Post Office + Postage $3.21 + Checking + + $ hledger codes + 123 + 124 + 126 + + $ hledger codes -E + 123 + 124 + + 126 + + commodities + List the commodity symbols used or declared in the journal. + + Flags: + --used list commodities used + --declared list commodities declared + --undeclared list commodities used but not declared + --unused list commodities declared but not used + + This command lists commodity symbols/names - all of them by default, or + just the ones which have been used in transactions or P directives, or + declared with commodity directives, or used but not declared, or de- + clared but not used. + + You can add cur: query arguments to further limit the commodities. + + descriptions + List the unique descriptions used in transactions. + + Flags: + no command-specific flags + + This command lists the unique descriptions that appear in transactions, + in alphabetic order. You can add a query to select a subset of trans- + actions. + + Example: + + $ hledger descriptions + Store Name + Gas Station | Petrol + Person A + + files + List all files included in the journal. With a REGEX argument, only + file names matching the regular expression (case sensitive) are shown. + + Flags: + no command-specific flags + + notes + List the unique notes that appear in transactions. + + Flags: + no command-specific flags + + This command lists the unique notes that appear in transactions, in al- + phabetic order. You can add a query to select a subset of transac- + tions. 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 + + payees + List the payee/payer names used or declared in the journal. + + Flags: + --used list payees used + --declared list payees declared + --undeclared list payees used but not declared + --unused list payees declared but not used + + This command lists unique payee/payer names - all of them by default, + or just the ones which have been used in transaction descriptions, or + declared with payee directives, or used but not declared, or declared + but not used. + + The payee/payer name 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 or pay- + ees. + + Example: + + $ hledger payees + Store Name + Gas Station + Person A + + prices + Print the market prices declared with P directives. With --infer-mar- + ket-prices, also show any additional prices inferred from costs. With + --show-reverse, also show additional prices inferred by reversing known + prices. + + Flags: + --show-reverse also show the prices inferred by reversing known + prices + + Price amounts are always displayed with their full precision, except + for reverse prices which are limited to 8 decimal digits. + + Prices can be filtered by a date:, cur: or amt: query. + + Generally if you run this command with --infer-market-prices --show-re- + verse, 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. + + stats + Show journal and performance statistics. + + Flags: + -v --verbose show more detailed output + -o --output-file=FILE write output to FILE. + + The stats command shows summary information for the whole journal, or a + matched part of it. With a reporting interval, it shows a report for + each report period. + + The default output is fairly impersonal, though it reveals the main + file name. With -v/--verbose, more details are shown, like file paths, + included files, and commodity names. + + It also shows some run time statistics: + + o elapsed time + + o throughput: the number of transactions processed per second + + o live: the peak memory in use by the program to do its work + + o alloc: the peak memory allocation from the OS as seen by GHC. Mea- + suring this externally, eg with GNU time, is more accurate; usually + that will be a larger number; sometimes (with swapping?) smaller. + + The stats command's run time is similar to that of a balance report. + + Example: + + $ hledger stats -f examples/1ktxns-1kaccts.journal + Main file : .../1ktxns-1kaccts.journal + Included files : 0 + Txns span : 2000-01-01 to 2002-09-27 (1000 days) + Last txn : 2002-09-26 (7827 days ago) + Txns : 1000 (1.0 per day) + Txns last 30 days : 0 (0.0 per day) + Txns last 7 days : 0 (0.0 per day) + Payees/descriptions : 1000 + Accounts : 1000 (depth 10) + Commodities : 26 + Market prices : 1000 + Runtime stats : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc + + This command supports the -o/--output-file option (but not -O/--out- + put-format). + + tags + List the tag names used or declared in the journal, or their values. + + Flags: + --used list tags used + --declared list tags declared + --undeclared list tags used but not declared + --unused list tags declared but not used + --values list tag values instead of tag names + --parsed show them in the order they were parsed (mostly), + including duplicates + + This command lists tag names - all of them by default, or just the ones + which have been used on transactions/postings/accounts, or declared + with tag directives, or used but not declared, or declared but not + used. + + You can add one TAGREGEX argument, to show only tags whose name is + matched by this case-insensitive, infix-matching regular expression. + + After that, you can add query arguments to filter the transactions, + postings, or accounts providing tags. + + With --values, 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.) + + Remember that accounts also acquire tags from their parents; postings + also acquire tags from their account and transaction; and transactions + also acquire tags from their postings. + +Standard report commands + print + Show full journal entries, representing transactions. + + Flags: + -x --explicit show all amounts explicitly + --invert display all amounts with reversed sign + --location add tags showing file paths and line numbers + -m --match=DESC fuzzy search for one recent transaction with + description closest to DESC + --new show only newer-dated transactions added in each + file since last run + --round=TYPE how much rounding or padding should be done when + displaying amounts ? + none - show original decimal digits, + as in journal (default) + soft - just add or remove decimal zeros + to match precision + hard - round posting amounts to precision + (can unbalance transactions) + all - also round cost amounts to precision + (can unbalance transactions) + --base-url=URLPREFIX in html output, generate links to hledger-web, + with this prefix. (Usually the base url shown by + hledger-web; can also be relative.) + -O --output-format=FMT select the output format. Supported formats: + txt, beancount, csv, tsv, html, fods, json, sql. + -o --output-file=FILE write output to FILE. A file extension matching + one of the above formats selects that format. + + The print command displays full journal entries (transactions) from the + journal file, sorted by date (or with --date2, by secondary date). + + Directives and inter-transaction comments are not shown, currently. + This means the print command is somewhat lossy, and if you are using it + to reformat/regenerate your journal you should take care to also copy + over the directives and inter-transaction comments. + + Eg: + + $ hledger print -f examples/sample.journal date:200806 + 2008/06/01 gift + assets:bank:checking $1 + income:gifts $-1 + + 2008/06/02 save + assets:bank:saving $1 + assets:bank:checking $-1 + + 2008/06/03 * eat & shop + expenses:food $1 + expenses:supplies $1 + assets:cash $-2 + + print amount explicitness + Normally, whether posting amounts are implicit or explicit is pre- + served. 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 mak- + ing 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 im- + plicit amount) to be split into multiple single-commodity postings, + keeping the output parseable. + + print alignment + Amounts are shown right-aligned within each transaction (but not + aligned across all transactions; you can achieve that with ledger-mode + in Emacs). + + print amount style + Amounts will be displayed mostly in their commodity's display style, + with standardised symbol placement, decimal mark, and digit group + marks. This does not apply to their decimal digits; print normally + shows the same decimal digits that are recorded in each journal entry. + + You can override the decimal precisions with print's special --round + option (since 1.32). --round tries to show amounts with their commodi- + ties' standard decimal precisions, increasingly strongly: + + o --round=none show amounts with original precisions (default) + + o --round=soft add/remove decimal zeros in amounts (except costs) + + o --round=hard round amounts (except costs), possibly hiding signifi- + cant digits + + o --round=all round all amounts and costs + + soft is good for non-lossy cleanup, displaying more consistent decimals + where possible, without making entries unbalanced. + + hard or all can be good for stronger cleanup, when decimal rounding is + wanted. Note rounding can produce unbalanced journal entries, perhaps + requiring manual fixup. + + print parseability + Normally, print's output is a valid hledger journal, which you can + "pipe" to a second hledger command for further processing. This is + sometimes convenient for achieving certain kinds of query (though less + needed now that queries have become more powerful): + + # 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 + + But here are some things which can cause print's output to become un- + parseable: + + o --round (see above) can disrupt transaction balancing. + + o Account aliases or pivoting can disrupt account names, balance asser- + tions, or balance assignments. + + o Value reporting also can disrupt balance assertions or balance as- + signments. + + o Auto postings can generate too many amountless postings. + + o --infer-costs or --infer-equity can generate too-complex redundant + costs. + + o Because print always shows transactions in date order, balance asser- + tions involving non-date-ordered transactions (and same-day postings) + could be disrupted. + + print, other features + With -B/--cost, amounts with costs are shown converted to cost. + + With --invert, posting amounts are shown with their sign flipped. It + could be useful if you have accidentally recorded some transactions + with the wrong signs. + + With --new, print shows only transactions it has not seen on a previous + run. This uses the same deduplication system as the import command. + (See import's docs for details.) + + With -m DESC/--match=DESC, print shows one recent transaction whose de- + scription 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. + + With --location, print adds the source file and line number to every + transaction, as a tag. + + print output format + This command also supports the output destination and output format op- + tions The output formats supported are txt, beancount (Added in 1.32), + csv, tsv (Added in 1.32), json and sql. + + The beancount format tries to produce Beancount-compatible output, as + follows: + + o Transaction and postings with unmarked status are converted to + cleared (*) status. + + o Transactions' payee and note are backslash-escaped and dou- + ble-quote-escaped and wrapped in double quotes. + + o Transaction tags are copied to Beancount #tag format. + + o Commodity symbols are converted to upper case, and a small number of + currency symbols like $ are converted to the corresponding currency + names. + + o Account name parts are capitalised and unsupported characters are re- + placed 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 ac- + counts into compliance.) + + o An open directive is generated for each account used, on the earliest + transaction date. + + Some limitations: + + o Balance assertions are removed. + + o Balance assignments become missing amounts. + + o Virtual and balanced virtual postings become regular postings. + + o 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","","","" + + o There is one CSV record per posting, with the parent transaction's + fields repeated. + + o 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.) + + o The amount is separated into "commodity" (the symbol) and "amount" + (numeric quantity) fields. + + o The numeric amount is repeated in either the "credit" or "debit" col- + umn, for convenience. (Those names are not accurate in the account- + ing sense; it just puts negative amounts under credit and zero or + greater amounts under debit.) + + aregister + (areg) + + Show the transactions and running balances in one account, with each + transaction on one line. + + Flags: + --txn-dates filter strictly by transaction date, not posting + date. Warning: this can show a wrong running + balance. + --no-elide don't show only 2 commodities per amount + --cumulative accumulation mode: show running total from report + start date + -H --historical accumulation mode: show historical running + total/balance (includes postings before report + start date) (default) + --invert display all amounts with reversed sign + --heading=YN show heading row above table: yes (default) or no + -w --width=N set output width (default: terminal width). -wN,M + sets description width as well. + --align-all guarantee alignment across all lines (slower) + -O --output-format=FMT select the output format. Supported formats: + txt, html, csv, tsv, json. + -o --output-file=FILE write output to FILE. A file extension matching + one of the above formats selects that format. + + aregister shows the overall transactions affecting a particular account + (and any subaccounts). Each report line represents one transaction in + this account. Transactions before the report start date are included + in the running balance (--historical mode is the default). You can + suppress this behaviour using the --cumulative option. + + This is a more "real world", bank-like view than the register command + (which shows individual postings, possibly from multiple accounts, not + necessarily in historical mode). As a quick rule of thumb: + + o aregister is best when reconciling real-world asset/liability ac- + counts + + o register is best when reviewing individual revenues/expenses. + + aregister requires one argument: the account to report on. You can + write either the full account name, or a case-insensitive regular ex- + pression 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:check- + ing 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 + historical balance report with similar arguments. + + Any additional arguments form a query which will filter the transac- + tions shown. Note some queries will disturb the running balance, caus- + ing 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: + + o the transaction's date (or the relevant posting's date if different, + see below) + + o the names of all the other account(s) involved in this transaction + (probably abbreviated) + + o the total change to this account's balance from this transaction + + o the account's historical running balance after this transaction. + + Transactions making a net change of zero are not shown by default; add + the -E/--empty flag to show them. + + For performance reasons, column widths are chosen based on the first + 1000 lines; this means unusually wide values in later lines can cause + visual discontinuities as column widths are adjusted. If you want to + ensure perfect alignment, at the cost of more time and memory, use the + --align-all flag. + + By default, aregister shows a heading above the data. However, when + reporting in a language different from English, it is easier to omit + this heading and prepend your own one. For this purpose, use the + --heading=no option. + + This command also supports the output destination and output format op- + tions. The output formats supported are txt, csv, tsv (Added in 1.32), + html, fods (Added in 1.41) and json. + + 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 post- + ings. 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. + + register + (reg) + + Show postings and their running total. + + Flags: + --cumulative accumulation mode: show running total from report + start date (default) + -H --historical accumulation mode: show historical running + total/balance (includes postings before report + start date) + -A --average show running average of posting amounts instead + of total (implies --empty) + -m --match=DESC fuzzy search for one recent posting with + description closest to DESC + -r --related show postings' siblings instead + --invert display all amounts with reversed sign + --sort=FIELDS sort by: date, desc, account, amount, absamount, + or a comma-separated combination of these. For a + descending sort, prefix with -. (Default: date) + -w --width=N set output width (default: terminal width). -wN,M + sets description width as well. + --align-all guarantee alignment across all lines (slower) + --base-url=URLPREFIX in html output, generate links to hledger-web, + with this prefix. (Usually the base url shown by + hledger-web; can also be relative.) + -O --output-format=FMT select the output format. Supported formats: + txt, csv, tsv, html, fods, json. + -o --output-file=FILE write output to FILE. A file extension matching + one of the above formats selects that format. + + The register command displays matched postings, across all accounts, in + date order, with their running total or running historical balance. + (See also the aregister command, which shows matched transactions in a + specific account.) + + register normally shows line per posting, but note that multi-commodity + amounts will occupy multiple lines (one line per commodity). + + It is typically used with a query selecting a particular account, to + see that account's activity: + + $ hledger register checking + 2008/01/01 income assets:bank:checking $1 $1 + 2008/06/01 gift assets:bank:checking $1 $2 + 2008/06/02 save assets:bank:checking $-1 $1 + 2008/12/31 pay off assets:bank:checking $-1 0 + + With --date2, it shows and sorts by secondary date instead. + + For performance reasons, column widths are chosen based on the first + 1000 lines; this means unusually wide values in later lines can cause + visual discontinuities as column widths are adjusted. If you want to + ensure perfect alignment, at the cost of more time and memory, use the + --align-all flag. + + The --historical/-H flag adds the balance from any undisplayed prior + postings to the running total. This is useful when you want to see + only recent activity, with a historically accurate running balance: + + $ hledger register checking -b 2008/6 --historical + 2008/06/01 gift assets:bank:checking $1 $2 + 2008/06/02 save assets:bank:checking $-1 $1 + 2008/12/31 pay off assets:bank:checking $-1 0 + + The --depth option limits the amount of sub-account detail displayed. + + The --average/-A flag shows the running average posting amount instead + of the running total (so, the final number displayed is the average for + the whole report period). This flag implies --empty (see below). It + is affected by --historical. It works best when showing just one ac- + count 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 num- + bers. It's also useful to show postings on the checking account to- + gether with the related account: + + The --sort=FIELDS flag sorts by the fields given, which can be any of + account, amount, absamount, date, or desc/description, optionally sepa- + rated by commas. For example, --sort account,amount will group all + transactions in each account, sorted by transaction amount. Each field + can be negated by a preceding -, so --sort -amount will show transac- + tions ordered from smallest amount to largest amount. + + $ hledger register --related --invert assets:checking + + With a reporting interval, register shows summary postings, one per in- + terval, 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 op- + tion helps with this, causing subaccounts to be aggregated: + + $ hledger register --monthly assets --depth 1 + 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 in- + tervals. 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 post- + ing will be shown and the program exit code will be non-zero. + + Custom register output + register normally uses the full terminal width (or 80 columns if it + can't detect that). You can override this with the --width/-w option. + + The description and account columns normally share the space equally + (about half of (width - 40) each). You can adjust this by adding a de- + scription width as part of --width's argument, comma-separated: --width + W,D . Here's a diagram (won't display correctly in --help): + + <--------------------------------- width (W) ----------------------------------> + date (10) description (D) account (W-41-D) amount (12) balance (12) + DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA + + and some examples: + + $ hledger reg # use terminal width (or 80 on windows) + $ hledger reg -w 100 # use width 100 + $ hledger reg -w 100,40 # set overall width 100, description width 40 + + This command also supports the output destination and output format op- + tions The output formats supported are txt, csv, tsv (Added in 1.32), + and json. + + balancesheet + (bs) + + Show the end balances in asset and liability accounts. Amounts are + shown with normal positive sign, as in conventional financial state- + ments. + + Flags: + --sum calculation mode: show sum of posting amounts + (default) + --valuechange calculation mode: show total change of value of + period-end historical balances (caused by deposits, + withdrawals, market price fluctuations) + --gain calculation mode: show unrealised capital + gain/loss (historical balance value minus cost + basis) + --count calculation mode: show the count of postings + --change accumulation mode: accumulate amounts from column + start to column end (in multicolumn reports) + --cumulative accumulation mode: accumulate amounts from report + start (specified by e.g. -b/--begin) to column end + -H --historical accumulation mode: accumulate amounts from + journal start to column end (includes postings + before report start date) (default) + -l --flat list/tree mode: show accounts as a flat list + (default). Amounts exclude subaccount amounts, + except where the account is depth-clipped. + -t --tree list/tree mode: show accounts as a tree. Amounts + include subaccount amounts. + --drop=N in list mode, omit N leading account name parts + --declared include non-parent declared accounts (best used + with -E) + -A --average show a row average column (in multicolumn + reports) + -T --row-total show a row total column (in multicolumn reports) + --summary-only display only row summaries (e.g. row total, + average) (in multicolumn reports) + -N --no-total omit the final total row + --no-elide in tree mode, don't squash boring parent accounts + --format=FORMATSTR use this custom line format (in simple reports) + -S --sort-amount sort by amount instead of account code/name + -% --percent express values in percentage of each column's + total + --layout=ARG how to show multi-commodity amounts: + 'wide[,WIDTH]': all commodities on one line + 'tall' : each commodity on a new line + 'bare' : bare numbers, symbols in a column + --base-url=URLPREFIX in html output, generate hyperlinks to + hledger-web, with this prefix. (Usually the base + url shown by hledger-web; can also be relative.) + -O --output-format=FMT select the output format. Supported formats: + txt, html, csv, tsv, json. + -o --output-file=FILE write output to FILE. A file extension matching + one of the above formats selects that format. + + This command displays a balance sheet, showing historical ending bal- + ances of asset and liability accounts. (To see equity as well, use the + balancesheetequity command.) + + Accounts declared with the Asset, Cash or Liability type are shown (see + account types). Or if no such accounts are declared, it shows + top-level accounts named asset or liability (case insensitive, plurals + allowed) and their subaccounts. + + Example: + + $ hledger balancesheet + Balance Sheet 2008-12-31 + + || 2008-12-31 + ====================++============ + Assets || + --------------------++------------ + assets:bank:saving || $1 + assets:cash || $-2 + --------------------++------------ + || $-1 + ====================++============ + Liabilities || + --------------------++------------ + liabilities:debts || $-1 + --------------------++------------ + || $-1 + ====================++============ + Net: || 0 + + This command is a higher-level variant of the balance command, and sup- + ports 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 op- + tions The output formats supported are txt, csv, tsv (Added in 1.32), + html, and json. + + balancesheetequity + (bse) + + This command displays a balance sheet, showing historical ending bal- + ances of asset, liability and equity accounts. Amounts are shown with + normal positive sign, as in conventional financial statements. + + Flags: + --sum calculation mode: show sum of posting amounts + (default) + --valuechange calculation mode: show total change of value of + period-end historical balances (caused by deposits, + withdrawals, market price fluctuations) + --gain calculation mode: show unrealised capital + gain/loss (historical balance value minus cost + basis) + --count calculation mode: show the count of postings + --change accumulation mode: accumulate amounts from column + start to column end (in multicolumn reports) + --cumulative accumulation mode: accumulate amounts from report + start (specified by e.g. -b/--begin) to column end + -H --historical accumulation mode: accumulate amounts from + journal start to column end (includes postings + before report start date) (default) + -l --flat list/tree mode: show accounts as a flat list + (default). Amounts exclude subaccount amounts, + except where the account is depth-clipped. + -t --tree list/tree mode: show accounts as a tree. Amounts + include subaccount amounts. + --drop=N in list mode, omit N leading account name parts + --declared include non-parent declared accounts (best used + with -E) + -A --average show a row average column (in multicolumn + reports) + -T --row-total show a row total column (in multicolumn reports) + --summary-only display only row summaries (e.g. row total, + average) (in multicolumn reports) + -N --no-total omit the final total row + --no-elide in tree mode, don't squash boring parent accounts + --format=FORMATSTR use this custom line format (in simple reports) + -S --sort-amount sort by amount instead of account code/name + -% --percent express values in percentage of each column's + total + --layout=ARG how to show multi-commodity amounts: + 'wide[,WIDTH]': all commodities on one line + 'tall' : each commodity on a new line + 'bare' : bare numbers, symbols in a column + --base-url=URLPREFIX in html output, generate hyperlinks to + hledger-web, with this prefix. (Usually the base + url shown by hledger-web; can also be relative.) + -O --output-format=FMT select the output format. Supported formats: + txt, html, csv, tsv, json. + -o --output-file=FILE write output to FILE. A file extension matching + one of the above formats selects that format. + + This report shows accounts declared with the Asset, Cash, Liability or + Equity type (see account types). Or if no such accounts are declared, + it shows top-level accounts named asset, liability or equity (case in- + sensitive, plurals allowed) and their subaccounts. + + Example: + + $ hledger balancesheetequity + Balance Sheet With Equity 2008-12-31 + + || 2008-12-31 + ====================++============ + Assets || + --------------------++------------ + assets:bank:saving || $1 + assets:cash || $-2 + --------------------++------------ + || $-1 + ====================++============ + Liabilities || + --------------------++------------ + liabilities:debts || $-1 + --------------------++------------ + || $-1 + ====================++============ + Equity || + --------------------++------------ + --------------------++------------ + || 0 + ====================++============ + Net: || 0 + + This command is a higher-level variant of the balance command, and sup- + ports many of that command's features, such as multi-period reports. + It is similar to hledger balance -H assets liabilities equity, but with + smarter account detection, and liabilities/equity displayed with their + sign flipped. + + This report is the easiest way to see if the accounting equation (A+L+E + = 0) is satisfied (after you have done a close --retain to merge rev- + enues and expenses with equity, and perhaps added --infer-equity to + balance your commodity conversions). + + This command also supports the output destination and output format op- + tions The output formats supported are txt, csv, tsv, html, and json. + + cashflow + (cf) + + This command displays a (simple) cashflow statement, showing the in- + flows and outflows affecting "cash" (ie, liquid, easily convertible) + assets. Amounts are shown with normal positive sign, as in conven- + tional financial statements. + + Flags: + --sum calculation mode: show sum of posting amounts + (default) + --valuechange calculation mode: show total change of value of + period-end historical balances (caused by deposits, + withdrawals, market price fluctuations) + --gain calculation mode: show unrealised capital + gain/loss (historical balance value minus cost + basis) + --count calculation mode: show the count of postings + --change accumulation mode: accumulate amounts from column + start to column end (in multicolumn reports) + (default) + --cumulative accumulation mode: accumulate amounts from report + start (specified by e.g. -b/--begin) to column end + -H --historical accumulation mode: accumulate amounts from + journal start to column end (includes postings + before report start date) + -l --flat list/tree mode: show accounts as a flat list + (default). Amounts exclude subaccount amounts, + except where the account is depth-clipped. + -t --tree list/tree mode: show accounts as a tree. Amounts + include subaccount amounts. + --drop=N in list mode, omit N leading account name parts + --declared include non-parent declared accounts (best used + with -E) + -A --average show a row average column (in multicolumn + reports) + -T --row-total show a row total column (in multicolumn reports) + --summary-only display only row summaries (e.g. row total, + average) (in multicolumn reports) + -N --no-total omit the final total row + --no-elide in tree mode, don't squash boring parent accounts + --format=FORMATSTR use this custom line format (in simple reports) + -S --sort-amount sort by amount instead of account code/name + -% --percent express values in percentage of each column's + total + --layout=ARG how to show multi-commodity amounts: + 'wide[,WIDTH]': all commodities on one line + 'tall' : each commodity on a new line + 'bare' : bare numbers, symbols in a column + --base-url=URLPREFIX in html output, generate hyperlinks to + hledger-web, with this prefix. (Usually the base + url shown by hledger-web; can also be relative.) + -O --output-format=FMT select the output format. Supported formats: + txt, html, csv, tsv, json. + -o --output-file=FILE write output to FILE. A file extension matching + one of the above formats selects that format. + + This report shows accounts declared with the Cash type (see account + types). Or if no such accounts are declared, it shows accounts + + o under a top-level account named asset (case insensitive, plural al- + lowed) + + o whose name contains some variation of cash, bank, checking or saving. + + More precisely: all accounts matching this case insensitive regular ex- + pression: + + ^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$) + + and their subaccounts. + + An example cashflow report: + + $ hledger cashflow + Cashflow Statement 2008 + + || 2008 + ====================++====== + Cash flows || + --------------------++------ + assets:bank:saving || $1 + assets:cash || $-2 + --------------------++------ + || $-1 + + This command is a higher-level variant of the balance command, and sup- + ports 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 op- + tions The output formats supported are txt, csv, tsv (Added in 1.32), + html, and json. + + incomestatement + (is) + + Show revenue inflows and expense outflows during the report period. + Amounts are shown with normal positive sign, as in conventional finan- + cial statements. + + Flags: + --sum calculation mode: show sum of posting amounts + (default) + --valuechange calculation mode: show total change of value of + period-end historical balances (caused by deposits, + withdrawals, market price fluctuations) + --gain calculation mode: show unrealised capital + gain/loss (historical balance value minus cost + basis) + --count calculation mode: show the count of postings + --change accumulation mode: accumulate amounts from column + start to column end (in multicolumn reports) + (default) + --cumulative accumulation mode: accumulate amounts from report + start (specified by e.g. -b/--begin) to column end + -H --historical accumulation mode: accumulate amounts from + journal start to column end (includes postings + before report start date) + -l --flat list/tree mode: show accounts as a flat list + (default). Amounts exclude subaccount amounts, + except where the account is depth-clipped. + -t --tree list/tree mode: show accounts as a tree. Amounts + include subaccount amounts. + --drop=N in list mode, omit N leading account name parts + --declared include non-parent declared accounts (best used + with -E) + -A --average show a row average column (in multicolumn + reports) + -T --row-total show a row total column (in multicolumn reports) + --summary-only display only row summaries (e.g. row total, + average) (in multicolumn reports) + -N --no-total omit the final total row + --no-elide in tree mode, don't squash boring parent accounts + --format=FORMATSTR use this custom line format (in simple reports) + -S --sort-amount sort by amount instead of account code/name + -% --percent express values in percentage of each column's + total + --layout=ARG how to show multi-commodity amounts: + 'wide[,WIDTH]': all commodities on one line + 'tall' : each commodity on a new line + 'bare' : bare numbers, symbols in a column + --base-url=URLPREFIX in html output, generate hyperlinks to + hledger-web, with this prefix. (Usually the base + url shown by hledger-web; can also be relative.) + -O --output-format=FMT select the output format. Supported formats: + txt, html, csv, tsv, json. + -o --output-file=FILE write output to FILE. A file extension matching + one of the above formats selects that format. + + This command displays an income statement, showing revenues and ex- + penses during one or more periods. + + It shows accounts declared with the Revenue or Expense type (see ac- + count types). Or if no such accounts are declared, it shows top-level + accounts named revenue or income or expense (case insensitive, plurals + allowed) and their subaccounts. + + Example: + + $ hledger incomestatement + Income Statement 2008 + + || 2008 + ===================++====== + Revenues || + -------------------++------ + income:gifts || $1 + income:salary || $1 + -------------------++------ + || $2 + ===================++====== + Expenses || + -------------------++------ + expenses:food || $1 + expenses:supplies || $1 + -------------------++------ + || $2 + ===================++====== + Net: || 0 + + This command is a higher-level variant of the balance command, and sup- + ports 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 op- + tions The output formats supported are txt, csv, tsv (Added in 1.32), + html, and json. + +Advanced report commands + balance + (bal) + + A flexible, general purpose "summing" report that shows accounts with + some kind of numeric data. This can be balance changes per period, end + balances, budget performance, unrealised capital gains, etc. + + Flags: + --sum calculation mode: show sum of posting amounts + (default) + --valuechange calculation mode: show total change of value of + period-end historical balances (caused by deposits, + withdrawals, market price fluctuations) + --gain calculation mode: show unrealised capital + gain/loss (historical balance value minus cost + basis) + --budget[=DESCPAT] calculation mode: show sum of posting amounts + together with budget goals defined by periodic + transactions. With a DESCPAT argument (must be + separated by = not space), + use only periodic transactions with matching + description + (case insensitive substring match). + --count calculation mode: show the count of postings + --change accumulation mode: accumulate amounts from column + start to column end (in multicolumn reports, + default) + --cumulative accumulation mode: accumulate amounts from report + start (specified by e.g. -b/--begin) to column end + -H --historical accumulation mode: accumulate amounts from + journal start to column end (includes postings + before report start date) + -l --flat list/tree mode: show accounts as a flat list + (default). Amounts exclude subaccount amounts, + except where the account is depth-clipped. + -t --tree list/tree mode: show accounts as a tree. Amounts + include subaccount amounts. + --drop=N in list mode, omit N leading account name parts + --declared include non-parent declared accounts (best used + with -E) + -A --average show a row average column (in multicolumn + reports) + -T --row-total show a row total column (in multicolumn reports) + --summary-only display only row summaries (e.g. row total, + average) (in multicolumn reports) + -N --no-total omit the final total row + --no-elide in tree mode, don't squash boring parent accounts + --format=FORMATSTR use this custom line format (in simple reports) + -S --sort-amount sort by amount instead of account code/name (in + flat mode). With multiple columns, sorts by the row + total, or by row average if that is displayed. + -% --percent express values in percentage of each column's + total + -r --related show the other accounts transacted with, instead + --invert display all amounts with reversed sign + --transpose switch rows and columns (use vertical time axis) + --layout=ARG how to lay out multi-commodity amounts and the + overall table: + 'wide[,W]': commodities on same line, up to W wide + 'tall' : commodities on separate lines + 'bare' : commodity symbols in a separate column + 'tidy' : each data field in its own column + --base-url=URLPREFIX in html output, generate links to hledger-web, + with this prefix. (Usually the base url shown by + hledger-web; can also be relative.) + -O --output-format=FMT select the output format. Supported formats: + txt, html, csv, tsv, json, fods. + -o --output-file=FILE write output to FILE. A file extension matching + one of the above formats selects that format. + + balance is one of hledger's oldest and most versatile commands, for + listing account balances, balance changes, values, value changes and + more, during one time period or many. Generally it shows a table, with + rows representing accounts, and columns representing periods. + + Note there are some variants of the balance command with convenient de- + faults, which are simpler to use: balancesheet, balancesheetequity, + cashflow and incomestatement. When you need more control, then use + balance. + + 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 + other balance-like commands as well (bs, cf, is..). + + balance can show.. + + o accounts as a list (-l) or a tree (-t) + + o optionally depth-limited (-[1-9]) + + o sorted by declaration order and name, or by amount + + ..and their.. + + o balance changes (the default) + + o or actual and planned balance changes (--budget) + + o or value of balance changes (-V) + + o or change of balance values (--valuechange) + + o or unrealised capital gain/loss (--gain) + + o or balance changes from sibling postings (--related/-r) + + o or postings count (--count) + + ..in.. + + o one time period (the whole journal period by default) + + o or multiple periods (-D, -W, -M, -Q, -Y, -p INTERVAL) + + ..either.. + + o per period (the default) + + o or accumulated since report start date (--cumulative) + + o or accumulated since account creation (--historical/-H) + + ..possibly converted to.. + + o cost (--value=cost[,COMM]/--cost/-B) + + o or market value, as of transaction dates (--value=then[,COMM]) + + o or at period ends (--value=end[,COMM]) + + o or now (--value=now) + + o or at some other date (--value=YYYY-MM-DD) + + ..with.. + + o totals (-T), averages (-A), percentages (-%), inverted sign (--in- + vert) + + o rows and columns swapped (--transpose) + + o another field used as account name (--pivot) + + o custom-formatted line items (single-period reports only) (--format) + + o commodities displayed on the same line or multiple lines (--layout) + + This command supports the output destination and output format options, + with output formats txt, csv, tsv (Added in 1.32), json, and (multi-pe- + riod reports only:) html, fods (Added in 1.40). In txt output in a + colour-supporting terminal, negative amounts are shown in red. + + Simple balance report + 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 bal- + ance at the end of the journal period; more on this below. + + Accounts are sorted by declaration order if any, and then alphabeti- + cally 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 (re- + vealing 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. + + 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 ac- + count/balance pair. It may contain any suitable text, with data fields + interpolated like so: + + %[MIN][.MAX](FIELDNAME) + + o MIN pads with spaces to at least this width (optional) + + o MAX truncates at this width (optional) + + o FIELDNAME must be enclosed in parentheses, and can be one of: + + o depth_spacer - a number of spaces equal to the account's depth, or + if MIN is specified, MIN * depth spaces. + + o account - the account's name + + o total - the account's balance/posted total, right justified + + Also, FMT can begin with an optional prefix to control how multi-com- + modity amounts are rendered: + + o %_ - render on multiple lines, bottom-aligned (the default) + + o %^ - render on multiple lines, top-aligned + + o %, - render on one line, comma-separated + + There are some quirks. Eg in one-line mode, %(depth_spacer) has no ef- + fect, instead %(account) has indentation built in. Experimentation + may be needed to get pleasing results. + + Some example formats: + + o %(total) - the account's total + + o %-20.20(account) - the account's name, left justified, padded to 20 + characters and clipped at 20 characters + + o %,%-50(account) %25(total) - account name padded to 50 characters, + total padded to 20 characters, with multiple commodities rendered on + one line + + o %20(total) %2(depth_spacer)%-(account) - the default format for the + single-column balance report + + 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 + + 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: + + o "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). + + o 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-plaintextac- + counting-users. A tree mode report's final total is the sum of the + top-level balances shown, not of all the balances shown. + + o Each group of sibling accounts (ie, under a common parent) is sorted + separately. + + 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 + + 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 + + Showing declared accounts + With --declared, accounts which have been declared with an account di- + rective 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 re- + port, even when you don't have transactions in all of your declared ac- + counts yet. + + Sorting by amount + With -S/--sort-amount, accounts with the largest (most positive) bal- + ances 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 commod- + ity 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 --in- + vert to flip the signs. Or you could use one of the higher-level bal- + ance reports (bs, is..), which flip the sign automatically (eg: hledger + is -MAS). + + 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 col- + umn 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: + + 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), bal- + ance 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: + + o The report's start/end dates will be expanded, if necessary, to fully + encompass the displayed subperiods (so that the first and last subpe- + riods have the same duration as the others). + + o Leading and trailing periods (columns) containing all zeroes are not + shown, unless -E/--empty is used. + + o Accounts (rows) containing all zeroes are not shown, unless + -E/--empty is used. + + o Amounts with many commodities are shown in abbreviated form, unless + --no-elide is used. + + o Average and/or total columns can be added with the -A/--average and + -T/--row-total flags. + + o The --transpose flag can be used to exchange rows and columns. + + o The --pivot FIELD option causes a different transaction field to be + used as "account name". See PIVOTING. + + o The --summary-only flag (--summary also works) hides all but the To- + tal and Average columns (those should be enabled with --row-total and + -A/--average). + + Multi-period reports with many periods can be too wide for easy viewing + in the terminal. Here are some ways to handle that: + + o Hide the totals row with -N/--no-total + + o Filter to a single currency with cur: + + o Convert to a single currency with -V [--infer-market-price] + + o Use a more compact layout like --layout=bare + + o Maximize the terminal window + + o Reduce the terminal's font size + + o View with a pager like less, eg: hledger bal -D --color=yes | less + -RS + + o 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) + + o Output as HTML and view with a browser: hledger bal -D -o a.html && + open a.html + + Balance change, end balance + It's important to be clear on the meaning of the numbers shown in bal- + ance reports. Here is some terminology we use: + + A balance change is the net amount added to, or removed from, an ac- + count 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 post- + ings.) + + Balance report modes + 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 ex- + perimentation to get familiar with all the report modes. + + There are three important option groups: + + hledger balance [CALCULATIONMODE] [ACCUMULATIONMODE] [VALUATIONMODE] + ... + + Calculation mode + The basic calculation to perform for each table cell. It is one of: + + o --sum : sum the posting amounts (default) + + o --budget : sum the amounts, but also show the budget goal amount (for + each account/period) + + o --valuechange : show the change in period-end historical balance val- + ues (caused by deposits, withdrawals, and/or market price fluctua- + tions) + + o --gain : show the unrealised capital gain/loss, (the current valued + balance minus each amount's original cost) + + o --count : show the count of postings + + Accumulation mode + How amounts should accumulate across a report's subperiods/columns. + Another way to say it: which time period's postings should contribute + to each cell's calculation. It is one of: + + o --change : calculate with postings from column start to column end, + ie "just this column". Typically used to see revenues/expenses. + (default for balance, cashflow, incomestatement) + + o --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. + + o --historical/-H : calculate with postings from journal start to col- + umn end, ie "all postings from before report start date until this + column's end". Typically used to see historical end balances of as- + sets/liabilities/equity. (default for balancesheet, balancesheete- + quity) + + Valuation mode + Which kind of value or cost conversion should be applied, if any, be- + fore displaying the report. See Cost reporting and Value reporting for + more about conversions. + + A valuation (or cost) mode can be selected with the --value option: + + o no conversion : don't convert to cost or value (default) + + o --value=cost[,COMM] : convert amounts to cost (then optionally to + some other commodity) + + o --value=then[,COMM] : convert amounts to market value on transaction + dates + + o --value=end[,COMM] : convert amounts to market value on period end + date(s) + (default with --valuechange, --gain) + + o --value=now[,COMM] : convert amounts to market value on today's date + + o --value=YYYY-MM-DD[,COMM] : convert amounts to market value on an- + other date + + or with the legacy -B/-V/-X options, which are equivalent and easier to + type: + + o -B/--cost : like --value=cost + + o -V/--market : like --value=end + + o -X COMM/--exchange COMM : like --value=end,COMM + + Note that --value can also convert to cost, as a convenience; but actu- + ally --cost and --value are independent options, and could be used to- + gether. + + Combining balance report modes + Most combinations of these modes should produce reasonable reports, but + if you find any that seem wrong or misleading, let us know. The fol- + lowing restrictions are applied: + + o --valuechange implies --value=end + + o --valuechange makes --change the default when used with the bal- + ancesheet/balancesheetequity commands + + o --cumulative or --historical disables --row-total/-T + + For reference, here is what the combinations of accumulation and valua- + tion show: + + Valua- no valuation --value= then --value= end --value= + tion:> YYYY-MM-DD + Accumu- /now + lation:v + ----------------------------------------------------------------------------------- + --change change in period sum of post- period-end DATE-value of + ing-date market value of change change in pe- + values in period in period riod + --cumu- change from re- sum of post- period-end DATE-value of + lative port start to ing-date market value of change change from + period end values from re- from report report start + port start to pe- start to period to period end + riod end end + --his- change from sum of post- period-end DATE-value of + torical journal start to ing-date market value of change change from + /-H period end (his- values from jour- from journal journal start + torical end bal- nal start to pe- start to period to period end + ance) riod end end + + Budget report + The --budget report is like a regular balance report, but with two main + differences: + + o Budget goals and performance percentages are also shown, in brackets + + o Accounts which don't have budget goals are hidden by default. + + This is useful for comparing planned and actual income, expenses, time + usage, etc. + + Periodic transaction rules are used to define budget goals. For exam- + ple, here's a periodic rule defining monthly goals for bus travel and + food expenses: + + ;; Budget + ~ monthly + (expenses:bus) $30 + (expenses:food) $400 + + After recording some actual expenses, + + ;; Two months worth of expenses + 2017-11-01 + income $-1950 + expenses:bus $35 + expenses:food:groceries $310 + expenses:food:dining $42 + expenses:movies $38 + assets:bank:checking + + 2017-12-01 + income $-2100 + expenses:bus $53 + expenses:food:groceries $380 + expenses:food:dining $32 + expenses:gifts $100 + assets:bank:checking + + we can see a budget report like this: + + $ hledger bal -M --budget + Budget performance in 2017-11-01..2017-12-31: + + || Nov Dec + ===============++============================================ + || $-425 $-565 + expenses || $425 [ 99% of $430] $565 [131% of $430] + expenses:bus || $35 [117% of $30] $53 [177% of $30] + expenses:food || $352 [ 88% of $400] $412 [103% of $400] + ---------------++-------------------------------------------- + || 0 [ 0% of $430] 0 [ 0% of $430] + + This is "goal-based budgeting"; you define goals for accounts and peri- + ods, often recurring, and hledger shows performance relative to the + goals. This contrasts with "envelope budgeting", which is more de- + tailed and strict - useful when cash is tight, but also quite a bit + more work. https://plaintextaccounting.org/Budgeting has more on this + topic. + + Using the budget report + Historically this report has been confusing and fragile. hledger's + version should be relatively robust and intuitive, but you may still + find surprises. Here are more notes to help with learning and trou- + bleshooting. + + o In the above example, expenses:bus and expenses:food are shown be- + cause they have budget goals during the report period. + + o Their parent expenses is also shown, with budget goals aggregated + from the children. + + o The subaccounts expenses:food:groceries and expenses:food:dining are + not shown since they have no budget goal of their own, but they con- + tribute to expenses:food's actual amount. + + o Unbudgeted accounts expenses:movies and expenses:gifts are also not + shown, but they contribute to expenses's actual amount. + + o The other unbudgeted accounts income and assets:bank:checking are + grouped as . + + o --depth or depth: can be used to limit report depth in the usual way + (but will not reveal unbudgeted subaccounts). + + o Amounts are always inclusive of subaccounts (even in -l/--list mode). + + o Numbers displayed in a --budget report will not always agree with the + totals, because of hidden unbudgeted accounts; this is normal. + -E/--empty can be used to reveal the hidden accounts. + + o In the periodic rules used for setting budget goals, unbalanced post- + ings are convenient. + + o You can filter budget reports with the usual queries, eg to focus on + particular accounts. It's common to restrict them to just expenses. + (The account is occasionally hard to exclude; this is + because of date surprises, discussed below.) + + o When you have multiple currencies, you may want to convert them to + one (-X COMM --infer-market-prices) and/or show just one at a time + (cur:COMM). If you do need to show multiple currencies at once, + --layout bare can be helpful. + + o You can "roll over" amounts (actual and budgeted) to the next period + with --cumulative. + + See also: https://hledger.org/budgeting.html. + + Budget date surprises + With small data, or when starting out, some of the generated budget + goal transaction dates might fall outside the report periods. Eg with + the following journal and report, the first period appears to have no + expenses:food budget. (Also the account should be ex- + cluded by the expenses query, but isn't.): + + ~ monthly in 2020 + (expenses:food) $500 + + 2020-01-15 + expenses:food $400 + assets:checking + + $ hledger bal --budget expenses + Budget performance in 2020-01-15: + + || 2020-01-15 + ===============++==================== + || $400 + expenses:food || 0 [ 0% of $500] + ---------------++-------------------- + || $400 [80% of $500] + + In this case, the budget goal transactions are generated on first days + of of month (this can be seen with hledger print --forecast tag:gener- + ated expenses). Whereas the report period defaults to just the 15th + day of january (this can be seen from the report table's column head- + ings). + + To fix this kind of thing, be more explicit about the report period + (and/or the periodic rules' dates). In this case, adding -b 2020 does + the trick. + + Selecting budget goals + By default, the budget report uses all available periodic transaction + rules to generate goals. This includes rules with a different report + interval from your report. Eg if you have daily, weekly and monthly + periodic rules, all of these will contribute to the goals in a monthly + budget report. + + You can select a subset of periodic rules by providing an argument to + the --budget flag. --budget=DESCPAT will match all periodic rules + whose description contains DESCPAT, a case-insensitive substring (not a + regular expression or query). This means you can give your periodic + rules descriptions (remember that two spaces are needed between period + expression and description), and then select from multiple budgets de- + fined in your journal. + + Budgeting vs forecasting + --forecast and --budget both use the periodic transaction rules in the + journal to generate temporary transactions for reporting purposes. + However they are separate features - though you can use both at the + same time if you want. Here are some differences between them: + + --forecast --budget + -------------------------------------------------------------------------- + is a general option; it enables fore- is a balance command option; it + casting with all reports selects the balance report's + budget mode + generates visible transactions which generates invisible transactions + appear in reports which produce goal amounts + generates forecast transactions from generates budget goal transac- + after the last regular transaction, to tions throughout the report pe- + the end of the report period; or with riod, optionally restricted by + an argument --forecast=PERIODEXPR gen- periods specified in the peri- + erates them throughout the specified odic transaction rules + period, both optionally restricted by + periods specified in the periodic + transaction rules + uses all periodic rules uses all periodic rules; or with + an argument --budget=DESCPAT + uses just the rules matched by + DESCPAT + + Balance report layout + The --layout option affects how balance and the other balance-like com- + mands show multi-commodity amounts and commodity symbols. It can im- + prove readability, for humans and/or machines (other software). It has + four possible values: + + o --layout=wide[,WIDTH]: commodities are shown on a single line, op- + tionally elided to WIDTH + + o --layout=tall: each commodity is shown on a separate line + + o --layout=bare: commodity symbols are in their own column, amounts are + bare numbers + + o --layout=tidy: data is normalised to easily-consumed "tidy" form, + with one row per data value. (This one is currently supported only + by the balance command.) + + Here are the --layout modes supported by each output format Only CSV + output supports all of them: + + - txt csv html json sql + ------------------------------------- + wide Y Y Y + tall Y Y Y + bare Y Y Y + tidy Y + + Examples: + + Wide layout + With many commodities, reports can be very wide: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide + Balance changes in 2012-01-01..2014-12-31: + + || 2012 2013 2014 Total + ==================++==================================================================================================================================================================================================================== + Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT + ------------------++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT + + A width limit reduces the width, but some commodities will be hidden: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32 + Balance changes in 2012-01-01..2014-12-31: + + || 2012 2013 2014 Total + ==================++=========================================================================================================================== + Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. + ------------------++--------------------------------------------------------------------------------------------------------------------------- + || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. + + 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 has its own + row, amounts are bare numbers, account names are repeated: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare + Balance changes in 2012-01-01..2014-12-31: + + || Commodity 2012 2013 2014 Total + ==================++============================================= + Assets:US:ETrade || GLD 0 70.00 0 70.00 + Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 + Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 + Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 + Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 + ------------------++--------------------------------------------- + || GLD 0 70.00 0 70.00 + || ITOT 10.00 18.00 -11.00 17.00 + || USD 337.18 -98.12 4881.44 5120.50 + || VEA 12.00 10.00 14.00 36.00 + || VHT 106.00 18.00 170.00 294.00 + + Bare layout also affects CSV output, which is useful for producing data + that is easier to consume, eg for making charts: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare + "account","commodity","balance" + "Assets:US:ETrade","GLD","70.00" + "Assets:US:ETrade","ITOT","17.00" + "Assets:US:ETrade","USD","5120.50" + "Assets:US:ETrade","VEA","36.00" + "Assets:US:ETrade","VHT","294.00" + "Total:","GLD","70.00" + "Total:","ITOT","17.00" + "Total:","USD","5120.50" + "Total:","VEA","36.00" + "Total:","VHT","294.00" + + Bare layout will sometimes display an extra row for the no-symbol com- + modity, because of zero amounts (hledger treats zeroes as commod- + ity-less, usually). This can break hledger-bar confusingly + (workaround: add a cur: query to exclude the no-symbol row). + + Tidy layout + This produces normalised "tidy data" (see + https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html) + where every variable has its own column and each row represents a sin- + gle data point. This is the easiest kind of data for other software to + consume: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy + "account","period","start_date","end_date","commodity","value" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" + + Balance report output + As noted in Output format, if you choose HTML output (by using -O html + or -o somefile.html), you can create a hledger.css file in the same di- + rectory to customise the report's appearance. + + The HTML and FODS output formats can generate hyperlinks to a + hledger-web register view for each account and period. E.g. if your + hledger-web server is reachable at http://localhost:5000 then you might + run the balance command with the extra option --base-url=http://local- + host:5000. You can also produce relative links, like + --base-url="some/path" or --base-url="".) + + Some useful balance reports + Some frequently used balance options/reports are: + + o bal -M revenues expenses + Show revenues/expenses in each month. Also available as the incomes- + tatement command. + + o bal -M -H assets liabilities + Show historical asset/liability balances at each month end. Also + available as the balancesheet command. + + o bal -M -H assets liabilities equity + Show historical asset/liability/equity balances at each month end. + Also available as the balancesheetequity command. + + o bal -M assets not:receivable + Show changes to liquid assets in each month. Also available as the + cashflow command. + + Also: + + o bal -M expenses -2 -SA + Show monthly expenses summarised to depth 2 and sorted by average + amount. + + o bal -M --budget expenses + Show monthly expenses and budget goals. + + o bal -M --valuechange investments + Show monthly change in market value of investment assets. + + o bal investments --valuechange -D date:lastweek amt:'>1000' -STA + [--invert] + Show top gainers [or losers] last week + + roi + Shows the time-weighted (TWR) and money-weighted (IRR) rate of return + on your investments. + + Flags: + --cashflow show all amounts that were used to compute + returns + --investment=QUERY query to select your investment transactions + --profit-loss=QUERY --pnl query to select profit-and-loss or + appreciation/valuation transactions + + At a minimum, you need to supply a query (which could be just an ac- + count 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 re- + quested. 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: + + o Error (NotBracketed): No solution for Internal Rate of Return (IRR). + Possible causes: IRR is huge (>1000000%), balance of investment be- + comes negative at some point in time. + + o Error (SearchFailed): Failed to find solution for Internal Rate of + Return (IRR). Either search does not converge to a solution, or con- + verges too slowly. + + Examples: + + o Using roi to compute total return of investment in stocks: + https://github.com/simonmichael/hledger/blob/master/examples/invest- + ing/roi-unrealised.ledger + + o Cookbook > Return on Investment: https://hledger.org/roi.html + + 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'" + + 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. + + o "Cash flow" is depositing or withdrawing money, buying or selling as- + sets, 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 + + o "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 re- + turn. + + 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 + + IRR and TWR explained + "ROI" stands for "return on investment". Traditionally this was com- + puted as a difference between current value of investment and its ini- + tial value, expressed in percentage of the initial value. + + However, this approach is only practical in simple cases, where invest- + ments receives no in-flows or out-flows of money, and where rate of + growth is fixed over time. For more complex scenarios you need differ- + ent 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 percent- + age 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 "unreal- + ized 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 ac- + count 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 invest- + ment and changes in its value change the value of "investment unit". + Change in "unit price" over the reporting period gives you rate of re- + turn of your investment, and make TWR less sensitive than IRR to the + effects of cash in-flows and out-flows. + + References: + + o Explanation of rate of return + + o Explanation of IRR + + o Explanation of TWR + + o IRR vs TWR + + o Examples of computing IRR and TWR and discussion of the limitations + of both metrics + +Chart commands + activity + Show an ascii barchart of posting counts per interval. + + Flags: + no command-specific flags + + The activity command displays an ascii histogram showing transaction + counts by day, week, month or other reporting interval (by day is the + default). With query arguments, it counts only matched transactions. + + Examples: + + $ hledger activity --quarterly + 2008-01-01 ** + 2008-04-01 ******* + 2008-07-01 + 2008-10-01 ** + +Data generation commands + close + (equity) + + close prints several kinds of "closing" and/or "opening" transactions, + useful in various situations: migrating balances to a new journal file, + retaining earnings into equity, consolidating balances, viewing lot + costs.. Like print, it prints valid journal entries. You can copy + these into your journal file(s) when you are happy with how they look. + + Flags: + --clopen[=TAGVAL] show closing and opening balances transactions, + for AL accounts by default + --close[=TAGVAL] show just a closing balances transaction + --open[=TAGVAL] show just an opening balances transaction + --assert[=TAGVAL] show a balance assertions transaction + --assign[=TAGVAL] show a balance assignments transaction + --retain[=TAGVAL] show a retain earnings transaction, for RX + accounts by default + -x --explicit show all amounts explicitly + --show-costs show amounts with different costs separately + --interleaved show source and destination postings together + --assertion-type=TYPE =, ==, =* or ==* + --close-desc=DESC set closing transaction's description + --close-acct=ACCT set closing transaction's destination account + --open-desc=DESC set opening transaction's description + --open-acct=ACCT set opening transaction's source account + --round=TYPE how much rounding or padding should be done when + displaying amounts ? + none - show original decimal digits, + as in journal (default) + soft - just add or remove decimal zeros + to match precision + hard - round posting amounts to precision + (can unbalance transactions) + all - also round cost amounts to precision + (can unbalance transactions) + + close has six modes, selected by choosing one of the mode flags: + --clopen, --close (default), --open, --assert, --assign, or --retain. + They are all doing the same kind of operation, but with different de- + faults for different situations. + + The journal entries generated by close will have a clopen: tag, which + is helpful when you want to exclude them from reports. If the main + journal file name contains a number, the tag's value will be that base + file name with the number incremented. Eg if the journal file is + 2025.journal, the tag will be clopen:2026. Or you can set the tag + value by providing an argument to the mode flag. Eg --close=foo or + --clopen=2025-main. + + close --clopen + This is useful if migrating balances to a new journal file at the start + of a new year. It prints a "closing balances" transaction that zeroes + out account balances (Asset and Liability accounts, by default), and an + opposite "opening balances" transaction that restores them again. Typ- + ically, you would run + + hledger close --clopen -e NEWYEAR >> $LEDGER_FILE + + and then move the opening transaction from the old file to the new file + (and probably also update your LEDGER_FILE environment variable). + + Why might you do this ? If your reports are fast, you may not need it. + But at some point you will probably want to partition your data by + time, for performance or data integrity or regulatory reasons. A new + file or set of files per year is common. Then, having each file/file- + set "bookended" with opening and closing balance transactions will al- + low you to freely pick and choose which files to read - just the cur- + rent year, any past year, any sequence of years, or all of them - while + showing correct account balances in each case. The earliest opening + balances transaction sets correct starting balances, and any later + closing/opening pairs will harmlessly cancel each other out. + + The balances will be transferred to and from equity:opening/closing + balances by default. You can override this by using --close-acct + and/or --open-acct. + + You can select a different set of accounts to close/open by providing + an account query. Eg to add Equity accounts, provide arguments like + assets liabilities equity or type:ALE. When migrating to a new file, + you'll usually want to bring along the AL or ALE accounts, but not the + RX accounts (Revenue, Expense). + + Assertions will be added indicating and checking the new balances of + the closed/opened accounts. + + close --close + This prints just the closing balances transaction of --clopen. It is + the default if you don't specify a mode. + + More customisation options are described below. Among other things, + you can use close --close to generate a transaction moving the balances + from any set of accounts, to a different account. (If you need to move + just a portion of the balance, see hledger-move.) + + close --open + This prints just the opening balances transaction of --clopen. (It is + similar to Ledger's equity command.) + + close --assert + This prints a transaction that asserts the account balances as they are + on the end date (and adds an assert: tag). It could be useful as docu- + mention and to guard against changes. + + close --assign + This prints a transaction that assigns the account balances as they are + on the end date (and adds an "assign:" tag). Unlike balance asser- + tions, assignments will post changes to balances as needed to reach the + specified amounts. + + This is another way to set starting balances when migrating to a new + file, and it will set them correctly even in the presence of earlier + files which do not have a closing balances transaction. However, it + can hide errors, and disturb the accounting equation, so --clopen is + usually recommended. + + close --retain + This is like --close, but it closes Revenue and Expense account bal- + ances by default. They will be transferred to equity:retained earn- + ings, or another account specified with --close-acct. + + Revenues and expenses correspond to changes in equity. They are cate- + gorised separately for reporting purposes, but traditionally at the end + of each accounting period, businesses consolidate them into equity, + This is called "retaining earnings", or "closing the books". + + In personal accounting, there's not much reason to do this, and most + people don't. (One reason to do it is to help the balancesheetequity + report show a zero total, demonstrating that the accounting equation + (A-L=E) is satisfied.) + + close customisation + In all modes, the following things can be overridden: + + o the accounts to be closed/opened, with account query arguments + + o the closing/opening dates, with -e OPENDATE + + o the balancing account, with --close-acct=ACCT and/or --open-acct=ACCT + + o the transaction descriptions, with --close-desc=DESC and + --open-desc=DESC + + o the transactions' clopen tag value, with a TAGVAL argument for the + mode flag (see above). + + By default, the closing date is yesterday, or the journal's end date, + whichever is later; and the opening date is always one day after the + closing date. You can change these by specifying a report end date; + the closing date will be the last day of the report period. Eg -e 2024 + means "close on 2023-12-31, open on 2024-01-01". + + With --x/--explicit, the balancing amount will be shown explicitly, and + if it involves multiple commodities, a separate posting will be gener- + ated for each of them (similar to print -x). + + With --interleaved, each individual transfer is shown with source and + destination postings next to each other (perhaps useful for trou- + bleshooting). + + With --show-costs, balances' costs are also shown, with different costs + kept separate. This may generate very large journal entries, if you + have many currency conversions or investment transactions. close + --show-costs is currently the best way to view investment lots with + hledger. (To move or dispose of lots, see the more capable + hledger-move script.) + + close and balance assertions + close adds balance assertions verifying that the accounts have been re- + set to zero in a closing transaction or restored to their previous bal- + ances in an opening transaction. These provide useful error checking, + but you can ignore them temporarily with -I, or remove them if you pre- + fer. + + Single-commodity, subaccount-exclusive balance assertions (=) are gen- + erated by default. This can be changed with --assertion-type='==*' + (eg). + + When running close you should probably avoid using -C, -R, status: + (filtering by status or realness) or --auto (generating postings), + since the generated balance assertions would then require these. + + Transactions with multiple dates (eg posting dates) spanning the file + boundary also can disrupt the balance assertions: + + 2023-12-30 a purchase made in december, cleared in january + expenses:food 5 + assets:bank:checking -5 ; date: 2023-01-02 + + To solve this you can transfer the money to and from a temporary ac- + count, splitting the multi-day transaction into two single-day transac- + tions: + + ; 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 + + close examples + Retain earnings + Record 2022's revenues/expenses as retained earnings on 2022-12-31, ap- + pending the generated transaction to the journal: + + $ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal + + After this, to see 2022's revenues and expenses you must exclude the + retain earnings transaction: + + $ hledger -f 2022.journal is not:desc:'retain earnings' + + Migrate balances to a new file + Close assets/liabilities on 2022-12-31 and re-open them on 2023-01-01: + + $ hledger close --clopen -f 2022.journal -p 2022 + # copy/paste the closing transaction to the end of 2022.journal + # copy/paste the opening transaction to the start of 2023.journal + + After this, to see 2022's end-of-year balances you must exclude the + closing balances transaction: + + $ hledger -f 2022.journal bs not:desc:'closing balances' + + For more flexibility, it helps to tag closing and opening transactions + with eg clopen:NEWYEAR, then you can ensure correct balances by exclud- + ing all opening/closing transactions except the first, like so: + + $ hledger bs -Y -f 2021.j -f 2022.j -f 2023.j expr:'tag:clopen=2021 or not tag:clopen' + $ hledger bs -Y -f 2021.j -f 2022.j expr:'tag:clopen=2021 or not tag:clopen' + $ hledger bs -Y -f 2022.j -f 2023.j expr:'tag:clopen=2022 or not tag:clopen' + $ hledger bs -Y -f 2021.j expr:'tag:clopen=2021 or not tag:clopen' + $ hledger bs -Y -f 2022.j expr:'tag:clopen=2022 or not tag:clopen' + $ hledger bs -Y -f 2023.j # unclosed file, no query needed + + More detailed close examples + See examples/multi-year. + + rewrite + Print all transactions, rewriting the postings of matched transactions. + For now the only rewrite available is adding new postings, like print + --auto. + + Flags: + --add-posting='ACCT AMTEXPR' add a posting to ACCT, which may be + parenthesised. AMTEXPR is either a literal + amount, or *N which means the transaction's + first matched amount multiplied by N (a + decimal number). Two spaces separate ACCT + and AMTEXPR. + --diff generate diff suitable as an input for + patch tool + + This is a start at a generic rewriter of transaction entries. It reads + the default journal and prints the transactions, like print, but adds + one or more specified postings to any transactions matching QUERY. The + posting amounts can be fixed, or a multiplier of the existing transac- + tion'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 in- + cludes a commodity name, the new posting amount will be in the new com- + modity; otherwise, it will be in the matched posting amount's commod- + ity. + + Re-write rules in a file + During the run this tool will execute so called "Automated Transac- + tions" 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 trans- + actions 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 post- + ings. + + 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 contain- + ing 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 + + rewrite vs. print --auto + This command predates print --auto, and currently does much the same + thing, but with these differences: + + o with multiple files, rewrite lets rules in any file affect all other + files. print --auto uses standard directive scoping; rules affect + only child files. + + o rewrite's query limits which transactions can be rewritten; all are + printed. print --auto's query limits which transactions are printed. + + o rewrite applies rules specified on command line or in the journal. + print --auto applies rules specified in the journal. + +Maintenance commands + check + Check for various kinds of errors in your data. + + Flags: + no command-specific flags + + hledger provides a number of built-in correctness checks to help vali- + date your data and prevent errors. Some are run automatically, some + when you enable --strict mode; or you can run any of them on demand by + providing them as arguments to the check command. check produces no + output and a zero exit code if all is well. Eg: + + hledger check # run basic checks + hledger check -s # run basic and strict checks + hledger check ordereddates payees # run basic checks and two others + + If you are an Emacs user, you can also configure flycheck-hledger to + run these checks, providing instant feedback as you edit the journal. + + Here are the checks currently available. They are generally checked in + the order they are shown here, and only the first failure will be re- + ported. + + Basic checks + These important checks are performed by default, by almost all hledger + commands: + + o parseable - data files are in a supported format, with no syntax er- + rors and no invalid include directives. This ensures that all files + exist and are readable. + + o autobalanced - all transactions are balanced, after automatically in- + ferring missing amounts and conversion rates and then converting + amounts to cost. This ensures that each transaction's journal entry + is well formed. + + o assertions - all balance assertions in the journal are passing. Bal- + ance assertions are a strong defense against errors, catching many + problems. This check is on by default, but if it gets in your way, + you can disable it temporarily with -I/--ignore-assertions, or as a + default by adding that flag to your config file. (Then use + -s/--strict or hledger check assertions when you want to enable it). + + Strict checks + When the -s/--strict flag is used (AKA strict mode), all commands will + perform the following additional checks (and assertions, above). These + provide extra error-catching power to help you keep your data clean and + correct: + + o balanced - like autobalanced, but implicit conversions between com- + modities are not allowed; all conversion transactions must use cost + notation or equity postings. This prevents wrong conversions caused + by typos. + + o commodities - all commodity symbols used must be declared. This + guards against mistyping or omitting commodity symbols. + + o accounts - all account names used must be declared. This prevents + the use of mis-spelled or outdated account names. + + Other checks + These are not wanted by everyone, but can be run using the check com- + mand: + + o tags - all tags used must be declared. This prevents mis-spelled tag + names. Note hledger fairly often finds unintended tags in comments. + + o payees - all payees used in transactions must be declared. This will + force you to declare any new payee name before using it. Most people + will probably find this a bit too strict. + + o ordereddates - within each file, transactions must be ordered by + date. This is a simple and effective error catcher. It's not in- + cluded in strict mode, but you can add it by running hledger check -s + ordereddates. If enabled, this check is performed before balance as- + sertions. + + o recentassertions - all accounts with balance assertions must have one + that's within the 7 days before their latest posting. This will en- + courage adding balance assertions for your active asset/liability ac- + counts, which in turn should encourage you to reconcile regularly + with those real world balances - another strong defense against er- + rors. (hledger close --assert >>$LEDGER_FILE is a convenient way to + add new balance assertions. Later these become quite redundant, and + you might choose to remove them to reduce clutter.) + + o uniqueleafnames - no two accounts may have the same last account name + part (eg the checking in assets:bank:checking). This ensures each + account can be matched by a unique short name, easier to remember and + to type. + + Custom checks + You can build your own custom checks with add-on command scripts. See + also Cookbook > Scripting. Here are some examples from hledger/bin/: + + o hledger-check-tagfiles - all tag values containing / exist as file + paths + + o hledger-check-fancyassertions - more complex balance assertions are + passing + + diff + Compares a particular account's transactions in two input files. It + shows any transactions to this account which are in one file but not in + the other. + + Flags: + no command-specific flags + + More precisely: for each posting affecting this account in either file, + this command looks for a corresponding posting in the other file which + posts the same amount to the same account (ignoring date, description, + etc). + + Since it compares postings, not transactions, this also works when mul- + tiple bank transactions have been combined into a single journal entry. + + This command is useful eg if you have downloaded an account's transac- + tions from your bank (eg as CSV data): when hledger and your bank dis- + agree 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: + + setup + Check the status of the hledger installation. + + Flags: + no command-specific flags + + setup tests your hledger installation and prints a list of results, + sometimes with helpful hints. This is a good first command to run af- + ter installing hledger. Also after upgrading, or when something's not + working, or just when you want a reminder of where things are. + + It makes one network request to detect the latest hledger release ver- + sion. It's ok if this fails or times out. It will use ANSI color by + default, unless disabled by NO_COLOR or --color=n. It does not use a + pager or a config file. + + It expects that the hledger version you are running is installed in + your PATH. If not, it will stop until you have done that (to keep + things simple). + + Example: + + $ hledger setup + Checking your hledger setup.. + Legend: good, neutral, unknown, warning + + hledger + * is a released version ? no hledger 1.42.99-gbca4b39c5-20250425, mac-aarch64 + * is up to date ? yes 1.42.99 installed, latest is 1.42.1 + * is a native binary for this machine ? yes aarch64 + * is installed in PATH ? yes /Users/simon/.local/bin/hledger + * has a system text encoding configured ? yes UTF-8, data files should use this encoding + * has a user config file ? (optional) no + * current directory has a local config ? yes /Users/simon/src/hledger/hledger.conf + * the config file is readable ? yes /Users/simon/src/hledger/hledger.conf + + terminal + * the NO_COLOR variable is defined ? no + * --color is configured by config file ? no + * hledger will use color by default ? yes + * the PAGER variable is defined ? yes less + * --pager is configured by config file ? no + * hledger will use a pager when needed ? yes /opt/homebrew/bin/less + * the LESS variable is defined ? yes + * the HLEDGER_LESS variable is defined ? no + * adjusting LESS variable for color etc. ? yes + * --pretty is enabled by config file ? no tables will use ASCII characters + * bash shell completions are installed ? ? + * zsh shell completions are installed ? ? + + journal + * the LEDGER_FILE variable is defined ? yes /Users/simon/finance/2025/2025.journal + * a default journal file is readable ? yes /Users/simon/finance/2025/2025.journal + * it includes additional files ? yes 15 + * all commodities are declared ? yes 10 + * all accounts are declared ? yes 160 + * all accounts have types ? no 14 untyped + * accounts of each type were detected ? yes ALERXCV + * commodities/accounts are checked ? no use -s to check commodities/accounts + * balance assertions are checked ? yes use -I to ignore assertions + + test + Run built-in unit tests. + + Flags: + no command-specific flags + + This command runs the unit tests built in to hledger and hledger-lib, + printing the results on stdout. If any test fails, the exit code will + be non-zero. + + This is mainly used by hledger developers, but you can also use it to + sanity-check the installed hledger executable on your platform. All + tests are expected to pass - if you ever see a failure, please report + as a bug! + + Any arguments before a -- argument will be passed to the tasty test + runner as test-selecting -p patterns, and any arguments after -- will + be passed to tasty unchanged. + + Examples: + + $ hledger test # run all unit tests + $ hledger test balance # run tests with "balance" in their name + $ hledger test -- -h # show tasty's options + +PART 5: COMMON TASKS + Here are some quick examples of how to do some basic tasks with + hledger. + +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. + +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 de- + scribed in OPTIONS, here are some tips that might help: + + o command-specific options must go after the command (it's fine to put + common options there too: hledger CMD OPTS ARGS) + + o you can run addon commands via hledger (hledger ui [ARGS]) or di- + rectly (hledger-ui [ARGS]) + + o enclose "problematic" arguments in single quotes + + o if needed, also add a backslash to hide regular expression metachar- + acters from the shell + + o to see how a misbehaving command line is being parsed, add --debug=2. + +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 () + +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/environ- + ment.plist like + + { + "LEDGER_FILE" : "~/finance/2023.journal" + } + + and then run killall Dock in a terminal window (or restart the ma- + chine). + + 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 per- + sists across a reboot, and if you need to be an Administrator): + + > CD + > MKDIR finance + > SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal" + + When correctly configured, in a new terminal window $env:LEDGER_FILE + will show the file path, and so will hledger files. + +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 re- + cent starting date, like today or the start of the week. You can al- + ways 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 bal- + ances on this date. Here are two ways to do it: + + o 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. + + o 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 + +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 + +Reconciling + Periodically you should reconcile - compare your hledger-reported bal- + ances 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 dis- + crepancies. + + 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 al- + ready-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 check- + ing -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 trans- + action history and running balance from your bank with the one re- + ported by hledger reg checking -C. This will be easier if you gen- + erally record transaction dates quite similar to your bank's clear- + ing dates. + + 3. Repeat for other asset/liability accounts. + + Tip: instead of the register command, use hledger-ui to see a live-up- + dating register while you edit the journal: hledger-ui --watch --regis- + ter 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 com- + mit: + + $ git commit -m 'txns' 2023.journal + +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 **** + +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. + +BUGS + We welcome bug reports in the hledger issue tracker + (https://bugs.hledger.org), or on the hledger chat or mail list + (https://hledger.org/support). + + Some known issues and limitations: + + hledger uses the system's text encoding when reading non-ascii text. + If no system encoding is configured, or if the data's encoding is dif- + ferent, hledger will give an error. (See Text encoding, Troubleshoot- + ing.) + + On Microsoft Windows, depending what kind of terminal window you use, + non-ascii characters, ANSI text formatting, and/or the add command's + TAB key, may not be fully supported. (For best results, try a power- + shell window.) + + When processing large data files, hledger uses more memory than Ledger. + + 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 ~/.lo- + cal/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 + o 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://stackover- + flow.com/a/7411509). On Windows, $env:LEDGER_FILE should show it. + + o 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. + + Text decoding issues: I get errors like "Illegal byte sequence" or "In- + valid or incomplete multibyte or wide character" or "commitAndRelease- + Buffer: invalid argument (invalid character)" + hledger usually needs its input to be decodable with the system lo- + cale's text encoding. See Text encoding and Install: Text encoding. + + 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. + + + +AUTHORS + Simon Michael and contributors. + See http://hledger.org/CREDITS.html + + +COPYRIGHT + Copyright 2007-2023 Simon Michael and contributors. + + +LICENSE + Released under GNU GPL v3 or later. + + +SEE ALSO + hledger(1), hledger-ui(1), hledger-web(1), ledger(1) + +hledger-1.50.3 November 2025 HLEDGER(1) diff --git a/hledger.cabal b/hledger.cabal --- a/hledger.cabal +++ b/hledger.cabal @@ -5,7 +5,7 @@ -- see: https://github.com/sol/hpack name: hledger -version: 1.50.2 +version: 1.50.3 synopsis: Command-line interface for the hledger accounting system description: The command-line interface for the hledger accounting system. Its basic function is to read a plain text file describing @@ -101,11 +101,6 @@ manual: True default: False -flag threaded - description: Build with support for multithreaded execution - manual: False - default: True - library exposed-modules: Hledger.Cli @@ -154,7 +149,7 @@ autogen-modules: Paths_hledger ghc-options: -Wall -Wno-incomplete-uni-patterns -Wno-missing-signatures -Wno-orphans -Wno-type-defaults -Wno-unused-do-bind -optP-Wno-nonportable-include-path - cpp-options: -DVERSION="1.50.2" + cpp-options: -DVERSION="1.50.3" build-depends: Decimal >=0.5.1 , Diff >=0.2 @@ -171,7 +166,7 @@ , githash >=0.1.6.2 , hashable >=1.2.4 , haskeline >=0.6 - , hledger-lib >=1.50.2 && <1.51 + , hledger-lib >=1.50.3 && <1.51 , http-client , http-types , lucid @@ -198,7 +193,7 @@ , utf8-string >=0.3.5 , utility-ht >=0.0.13 , wizards >=1.0 - default-language: Haskell2010 + default-language: GHC2021 if (flag(debug)) cpp-options: -DDEBUG @@ -210,8 +205,8 @@ Paths_hledger hs-source-dirs: app - ghc-options: -Wall -Wno-incomplete-uni-patterns -Wno-missing-signatures -Wno-orphans -Wno-type-defaults -Wno-unused-do-bind -optP-Wno-nonportable-include-path -with-rtsopts=-T - cpp-options: -DVERSION="1.50.2" + ghc-options: -Wall -Wno-incomplete-uni-patterns -Wno-missing-signatures -Wno-orphans -Wno-type-defaults -Wno-unused-do-bind -optP-Wno-nonportable-include-path -threaded -with-rtsopts=-T + cpp-options: -DVERSION="1.50.3" build-depends: Decimal >=0.5.1 , aeson >=1 && <2.3 @@ -227,7 +222,7 @@ , githash >=0.1.6.2 , haskeline >=0.6 , hledger - , hledger-lib >=1.50.2 && <1.51 + , hledger-lib >=1.50.3 && <1.51 , http-client , http-types , math-functions >=0.3.3.0 @@ -252,11 +247,9 @@ , utf8-string >=0.3.5 , utility-ht >=0.0.13 , wizards >=1.0 - default-language: Haskell2010 + default-language: GHC2021 if (flag(debug)) cpp-options: -DDEBUG - if flag(threaded) - ghc-options: -threaded test-suite unittest type: exitcode-stdio-1.0 @@ -264,7 +257,7 @@ hs-source-dirs: test ghc-options: -Wall -Wno-incomplete-uni-patterns -Wno-missing-signatures -Wno-orphans -Wno-type-defaults -Wno-unused-do-bind -optP-Wno-nonportable-include-path - cpp-options: -DVERSION="1.50.2" + cpp-options: -DVERSION="1.50.3" build-depends: Decimal >=0.5.1 , aeson >=1 && <2.3 @@ -280,7 +273,7 @@ , githash >=0.1.6.2 , haskeline >=0.6 , hledger - , hledger-lib >=1.50.2 && <1.51 + , hledger-lib >=1.50.3 && <1.51 , http-client , http-types , math-functions >=0.3.3.0 @@ -305,7 +298,7 @@ , utf8-string >=0.3.5 , utility-ht >=0.0.13 , wizards >=1.0 - default-language: Haskell2010 + default-language: GHC2021 if (flag(debug)) cpp-options: -DDEBUG @@ -331,7 +324,7 @@ , githash >=0.1.6.2 , haskeline >=0.6 , hledger - , hledger-lib >=1.50.2 && <1.51 + , hledger-lib >=1.50.3 && <1.51 , html , http-client , http-types @@ -358,6 +351,6 @@ , utility-ht >=0.0.13 , wizards >=1.0 buildable: False - default-language: Haskell2010 + default-language: GHC2021 if (flag(debug)) cpp-options: -DDEBUG