summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--CHANGES44
-rw-r--r--Hledger/Cli/CliOptions.hs12
-rw-r--r--Hledger/Cli/Commands.hs11
-rw-r--r--Hledger/Cli/Commands/Balance.hs226
-rwxr-xr-xHledger/Cli/Commands/Import.hs4
-rw-r--r--Hledger/Cli/CompoundBalanceCommand.hs2
-rw-r--r--Hledger/Cli/Main.hs2
-rw-r--r--Hledger/Cli/Utils.hs23
-rw-r--r--Text/Tabular/AsciiWide.hs111
-rw-r--r--bench/bench.hs7
-rw-r--r--embeddedfiles/hledger-api.12
-rw-r--r--embeddedfiles/hledger-api.info8
-rw-r--r--embeddedfiles/hledger-api.txt2
-rw-r--r--embeddedfiles/hledger-ui.12
-rw-r--r--embeddedfiles/hledger-ui.info32
-rw-r--r--embeddedfiles/hledger-ui.txt2
-rw-r--r--embeddedfiles/hledger-web.12
-rw-r--r--embeddedfiles/hledger-web.info8
-rw-r--r--embeddedfiles/hledger-web.txt2
-rw-r--r--embeddedfiles/hledger.1338
-rw-r--r--embeddedfiles/hledger.info612
-rw-r--r--embeddedfiles/hledger.txt593
-rw-r--r--embeddedfiles/hledger_csv.52
-rw-r--r--embeddedfiles/hledger_csv.info60
-rw-r--r--embeddedfiles/hledger_csv.txt2
-rw-r--r--embeddedfiles/hledger_journal.5390
-rw-r--r--embeddedfiles/hledger_journal.info602
-rw-r--r--embeddedfiles/hledger_journal.txt386
-rw-r--r--embeddedfiles/hledger_timeclock.52
-rw-r--r--embeddedfiles/hledger_timeclock.info4
-rw-r--r--embeddedfiles/hledger_timeclock.txt2
-rw-r--r--embeddedfiles/hledger_timedot.52
-rw-r--r--embeddedfiles/hledger_timedot.info8
-rw-r--r--embeddedfiles/hledger_timedot.txt2
-rw-r--r--hledger.1338
-rw-r--r--hledger.cabal98
-rw-r--r--hledger.info612
-rw-r--r--hledger.txt593
38 files changed, 2545 insertions, 2603 deletions
diff --git a/CHANGES b/CHANGES
index fa2e7d5..14b4fee 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,6 +1,50 @@
User-visible changes in the hledger command line tool.
+# 1.9.1 (2018/4/30)
+
+* use hledger-lib 1.9.1
+
+* budget (balance --budget): budgets can be built from periodic
+ transactions with different intervals again. In 1.9, budgets were
+ restricted to a single interval, but this was a mistake. This
+ restores the 1.5 behaviour.
+
+* budget: budget reports are more intuitive and much less likely to
+ produce no output.
+
+* budget: when no report interval is specified, a budget report for
+ the whole journal period is shown.
+
+* budget: periodic transactions and the requested report period can
+ each have their own start/end dates, and the resulting report will
+ span the union of those periods, showing zeroes where data is
+ missing.
+
+* budget: total row and total/average columns are now calculated correctly
+
+* budget: actual, percentage, and goal amounts are now aligned in
+ columns for better readability (usually, unless numbers get huge).
+
+* budget: combining --budget and --sort-amount is not yet supported
+ and now gives an error.
+
+* csv: handle "-%amount" in a rule when the CSV amount is parenthesised (#736)
+
+* journal: automated postings are now generated early, before journal finalisation,
+ so they are present for amount inference, transaction balancing, and balance assertions
+ (#729)
+
+* cli: command-line account aliases are now applied early, before journal finalisation,
+ so they are equivalent to alias directives in the journal (#730)
+
+* journal: inferred amounts now have the appropriate standard amount style applied
+ (setting the precision correctly, eg). (#737)
+
+* journal: when checking for balanced transactions, amount styles declared with
+ commodity directives are also used (previously only inferred amount styles were).
+
+
# 1.9 (2018/3/31)
* support ghc 8.4, latest deps
diff --git a/Hledger/Cli/CliOptions.hs b/Hledger/Cli/CliOptions.hs
index 2a4ec38..64f7999 100644
--- a/Hledger/Cli/CliOptions.hs
+++ b/Hledger/Cli/CliOptions.hs
@@ -44,7 +44,6 @@ module Hledger.Cli.CliOptions (
-- possibly these should move into argsToCliOpts
-- * CLI option accessors
-- | These do the extra processing required for some options.
- aliasesFromOpts,
journalFilePathFromOpts,
rulesFilePathFromOpts,
outputFileFromOpts,
@@ -54,7 +53,6 @@ module Hledger.Cli.CliOptions (
replaceNumericFlags,
-- | For register:
registerWidthsFromOpts,
- maybeAccountNameDrop,
-- | For balance:
lineFormatFromOpts,
@@ -484,11 +482,6 @@ getHledgerCliOpts mode' = do
-- CliOpts accessors
--- | Get the account name aliases from options, if any.
-aliasesFromOpts :: CliOpts -> [AccountAlias]
-aliasesFromOpts = map (\a -> fromparse $ runParser accountaliasp ("--alias "++quoteIfNeeded a) $ T.pack a)
- . aliases_ . inputopts_
-
-- | Get the (tilde-expanded, absolute) journal file path from
-- 1. options, 2. an environment variable, or 3. the default.
-- Actually, returns one or more file paths. There will be more
@@ -590,11 +583,6 @@ registerWidthsFromOpts CliOpts{width_=Just s} =
eof
return (totalwidth, descwidth)
--- | Drop leading components of accounts names as specified by --drop, but only in --flat mode.
-maybeAccountNameDrop :: ReportOpts -> AccountName -> AccountName
-maybeAccountNameDrop opts a | tree_ opts = a
- | otherwise = accountNameDrop (drop_ opts) a
-
-- for balance, currently:
-- | Parse the format option if provided, possibly returning an error,
diff --git a/Hledger/Cli/Commands.hs b/Hledger/Cli/Commands.hs
index c558da5..d3d4a8b 100644
--- a/Hledger/Cli/Commands.hs
+++ b/Hledger/Cli/Commands.hs
@@ -37,6 +37,7 @@ module Hledger.Cli.Commands (
where
import Control.Monad
+import Data.Default
import Data.List
import Data.List.Split (splitOn)
#if !(MIN_VERSION_base(4,11,0))
@@ -269,8 +270,8 @@ tests_Hledger_Cli_Commands = TestList [
,"apply account directive" ~:
let ignoresourcepos j = j{jtxns=map (\t -> t{tsourcepos=nullsourcepos}) (jtxns j)} in
- let sameParse str1 str2 = do j1 <- readJournal Nothing Nothing True Nothing str1 >>= either error' (return . ignoresourcepos)
- j2 <- readJournal Nothing Nothing True Nothing str2 >>= either error' (return . ignoresourcepos)
+ let sameParse str1 str2 = do j1 <- readJournal def Nothing str1 >>= either error' (return . ignoresourcepos)
+ j2 <- readJournal def Nothing str2 >>= either error' (return . ignoresourcepos)
j1 `is` j2{jlastreadtime=jlastreadtime j1, jfiles=jfiles j1} --, jparsestate=jparsestate j1}
in sameParse
("2008/12/07 One\n alpha $-1\n beta $1\n" <>
@@ -287,13 +288,13 @@ tests_Hledger_Cli_Commands = TestList [
)
,"apply account directive should preserve \"virtual\" posting type" ~: do
- j <- readJournal Nothing Nothing True Nothing "apply account test\n2008/12/07 One\n (from) $-1\n (to) $1\n" >>= either error' return
+ j <- readJournal def Nothing "apply account test\n2008/12/07 One\n (from) $-1\n (to) $1\n" >>= either error' return
let p = head $ tpostings $ head $ jtxns j
assertBool "" $ paccount p == "test:from"
assertBool "" $ ptype p == VirtualPosting
,"account aliases" ~: do
- j <- readJournal Nothing Nothing True Nothing "!alias expenses = equity:draw:personal\n1/1\n (expenses:food) 1\n" >>= either error' return
+ j <- readJournal def Nothing "!alias expenses = equity:draw:personal\n1/1\n (expenses:food) 1\n" >>= either error' return
let p = head $ tpostings $ head $ jtxns j
assertBool "" $ paccount p == "equity:draw:personal:food"
@@ -315,7 +316,7 @@ tests_Hledger_Cli_Commands = TestList [
-- `is` "aa:aa:aaaaaaaaaaaaaa")
,"default year" ~: do
- j <- readJournal Nothing Nothing True Nothing defaultyear_journal_txt >>= either error' return
+ j <- readJournal def Nothing defaultyear_journal_txt >>= either error' return
tdate (head $ jtxns j) `is` fromGregorian 2009 1 1
return ()
diff --git a/Hledger/Cli/Commands/Balance.hs b/Hledger/Cli/Commands/Balance.hs
index 43ea65a..83a48fc 100644
--- a/Hledger/Cli/Commands/Balance.hs
+++ b/Hledger/Cli/Commands/Balance.hs
@@ -245,25 +245,24 @@ module Hledger.Cli.Commands.Balance (
,multiBalanceReportAsCsv
,multiBalanceReportAsHtml
,multiBalanceReportHtmlRows
- ,renderBalanceReportTable
,balanceReportAsTable
+ ,balanceReportTableAsText
,tests_Hledger_Cli_Commands_Balance
) where
-import Data.Decimal
+import Control.Monad (when)
import Data.List
import Data.Maybe
-import qualified Data.Map as Map
+--import qualified Data.Map as Map
import qualified Data.Text as T
import qualified Data.Text.Lazy as TL
import System.Console.CmdArgs.Explicit as C
-import Data.Decimal (roundTo)
import Lucid as L
import Text.CSV
import Test.HUnit
import Text.Printf (printf)
import Text.Tabular as T
-import Text.Tabular.AsciiWide
+--import Text.Tabular.AsciiWide
import Hledger
import Hledger.Cli.CliOptions
@@ -310,9 +309,24 @@ balance opts@CliOpts{rawopts_=rawopts,reportopts_=ropts} j = do
Left err -> error' $ unlines [err]
Right _ -> do
let format = outputFormatFromOpts opts
+ budget = boolopt "budget" rawopts
interval = interval_ ropts
- case interval of
- NoInterval -> do
+ case (budget, interval) of
+ (True, _) -> do
+ -- single or multicolumn budget report
+ when (sort_amount_ ropts) $ error' "Sorry, --sort-amount is not yet supported with --budget." -- TODO
+ reportspan <- reportSpan j ropts
+ let budgetreport = dbg1 "budgetreport" $ budgetReport ropts assrt showunbudgeted reportspan d j
+ where
+ showunbudgeted = boolopt "show-unbudgeted" rawopts
+ assrt = not $ ignore_assertions_ $ inputopts_ opts
+ render = case format of
+ "csv" -> const $ error' "Sorry, CSV output is not yet implemented for this kind of report." -- TODO
+ "html" -> const $ error' "Sorry, HTML output is not yet implemented for this kind of report." -- TODO
+ _ -> budgetReportAsText ropts
+ writeOutput opts $ render budgetreport
+
+ (False, NoInterval) -> do
-- single column balance report
let report
| balancetype_ ropts `elem` [HistoricalBalance, CumulativeChange]
@@ -327,20 +341,7 @@ balance opts@CliOpts{rawopts_=rawopts,reportopts_=ropts} j = do
_ -> balanceReportAsText
writeOutput opts $ render ropts report
- _ | boolopt "budget" rawopts -> do
- -- multi column budget report
- reportspan <- reportSpan j ropts
- let budget = budgetJournal opts reportspan j
- j' = budgetRollUp opts budget j
- report = dbg1 "report" $ multiBalanceReport ropts (queryFromOpts d ropts) j'
- budgetReport = dbg1 "budgetreport" $ multiBalanceReport ropts (queryFromOpts d ropts) budget
- render = case format of
- "csv" -> const $ error' "Sorry, CSV output is not yet implemented for this kind of report." -- TODO
- "html" -> const $ error' "Sorry, HTML output is not yet implemented for this kind of report." -- TODO
- _ -> multiBalanceReportWithBudgetAsText ropts budgetReport
- writeOutput opts $ render report
-
- | otherwise -> do
+ _ -> do
-- multi column balance report
let report = multiBalanceReport ropts (queryFromOpts d ropts) j
render = case format of
@@ -349,50 +350,7 @@ balance opts@CliOpts{rawopts_=rawopts,reportopts_=ropts} j = do
_ -> multiBalanceReportAsText ropts
writeOutput opts $ render report
--- | Re-map account names to closest parent with periodic transaction from budget.
--- Accounts that don't have suitable parent are either remapped to "<unbudgeted>:topAccount"
--- or left as-is if --show-unbudgeted is provided.
-budgetRollUp :: CliOpts -> Journal -> Journal -> Journal
-budgetRollUp CliOpts{rawopts_=rawopts} budget j = j { jtxns = remapTxn <$> jtxns j }
- where
- budgetAccounts = nub $ concatMap (map paccount . ptpostings) $ jperiodictxns budget
- remapAccount origAcctName = remapAccount' origAcctName
- where
- remapAccount' acctName
- | acctName `elem` budgetAccounts = acctName
- | otherwise =
- case parentAccountName acctName of
- "" | boolopt "show-unbudgeted" rawopts -> origAcctName
- | otherwise -> T.append (T.pack "<unbudgeted>:") acctName -- TODO: --drop should not remove this
- parent -> remapAccount' parent
- remapPosting p = p { paccount = remapAccount $ paccount p, porigin = Just . fromMaybe p $ porigin p }
- remapTxn = mapPostings (map remapPosting)
- mapPostings f t = txnTieKnot $ t { tpostings = f $ tpostings t }
-
--- | Select all periodic transactions from the given journal which
--- match the requested report interval, and use them to generate
--- budget transactions (like forecast transactions) in the specified
--- report period (calculated in IO and passed in).
-budgetJournal :: CliOpts -> DateSpan -> Journal -> Journal
-budgetJournal opts reportspan j = journalBalanceTransactions' opts j { jtxns = budgetts }
- where
- budgetinterval = dbg2 "budgetinterval" $ intervalFromRawOpts $ rawopts_ opts
- budgetspan = dbg2 "budgetspan" $ reportspan
- budgetts =
- dbg1 "budgetts" $
- [makeBudgetTxn t
- | pt <- jperiodictxns j
- , periodTransactionInterval pt == Just budgetinterval
- , t <- runPeriodicTransaction pt budgetspan
- ]
- makeBudgetTxn t = txnTieKnot $ t { tdescription = T.pack "Budget transaction" }
- journalBalanceTransactions' opts j =
- let assrt = not . ignore_assertions_ $ inputopts_ opts
- in
- either error' id $ journalBalanceTransactions assrt j
-
-
--- single-column balance reports
+-- rendering single-column balance reports
-- | Find the best commodity to convert to when asked to show the
-- market value of this commodity on the given date. That is, the one
@@ -522,7 +480,7 @@ renderComponent1 opts (acctname, depth, total) (FormatField ljust min max field)
| otherwise = showMixedAmountWithoutPrice
_ -> ""
--- multi-column balance reports
+-- rendering multi-column balance reports
-- | Render a multi-column balance report as CSV.
-- The CSV will always include the initial headings row,
@@ -641,7 +599,7 @@ multiBalanceReportHtmlFootRow ropts (acct:rest) =
multiBalanceReportAsText :: ReportOpts -> MultiBalanceReport -> String
multiBalanceReportAsText opts r =
printf "%s in %s:\n\n" desc (showDateSpan $ multiBalanceReportSpan r)
- ++ renderBalanceReportTable opts tabl
+ ++ balanceReportTableAsText opts tabl
where
tabl = balanceReportAsTable opts r
desc = case balancetype_ opts of
@@ -649,129 +607,11 @@ multiBalanceReportAsText opts r =
CumulativeChange -> "Ending balances (cumulative)"
HistoricalBalance -> "Ending balances (historical)"
-type ActualAmount = MixedAmount
-type BudgetAmount = MixedAmount
-type ActualAmountsReport = MultiBalanceReport
-type BudgetAmountsReport = MultiBalanceReport
-type ActualAmountsTable = Table String String MixedAmount
-type BudgetAmountsTable = Table String String MixedAmount
-type ActualAndBudgetAmountsTable = Table String String (Maybe MixedAmount, Maybe MixedAmount)
-type Percentage = Decimal
-
--- | Given two multi-column balance reports, the first representing a budget
--- (target change amounts) and the second representing actual change amounts,
--- render a budget report as plain text suitable for console output.
--- The reports should have the same number of columns.
-multiBalanceReportWithBudgetAsText :: ReportOpts -> BudgetAmountsReport -> ActualAmountsReport -> String
-multiBalanceReportWithBudgetAsText opts budgetr actualr =
- printf "%s in %s:\n\n" desc (showDateSpan $ multiBalanceReportSpan actualr)
- ++ renderBalanceReportTable' opts showcell actualandbudgetamts
- where
- desc :: String
- desc = case balancetype_ opts of
- PeriodChange -> "Balance changes"
- CumulativeChange -> "Ending balances (cumulative)"
- HistoricalBalance -> "Ending balances (historical)"
-
- actualandbudgetamts :: ActualAndBudgetAmountsTable
- actualandbudgetamts = combineTables (balanceReportAsTable opts actualr) (balanceReportAsTable opts budgetr)
-
- showcell :: (Maybe ActualAmount, Maybe BudgetAmount) -> String
- showcell (mactual, mbudget) = actualstr ++ " " ++ budgetstr
- where
- actualwidth = 7
- percentwidth = 4
- budgetwidth = 5
- actualstr = printf ("%"++show actualwidth++"s") (maybe "" showamt mactual)
- budgetstr = case (mactual, mbudget) of
- (_, Nothing) -> replicate (percentwidth + 7 + budgetwidth) ' '
- (mactual, Just budget) ->
- case percentage mactual budget of
- Just pct ->
- printf ("[%"++show percentwidth++"s%% of %"++show budgetwidth++"s]")
- (show $ roundTo 0 pct) (showamt budget)
- Nothing ->
- printf ("["++replicate (percentwidth+5) ' '++"%"++show budgetwidth++"s]")
- (showamt budget)
-
- percentage :: Maybe ActualAmount -> BudgetAmount -> Maybe Percentage
- percentage Nothing _ = Nothing
- percentage (Just actual) budget =
- -- percentage of budget consumed is always computed in the cost basis
- case (toCost actual, toCost budget) of
- (Mixed [a1], Mixed [a2])
- | isReallyZeroAmount a1 -> Just 0 -- if there are no postings, we consumed 0% of budget
- | acommodity a1 == acommodity a2 && aquantity a2 /= 0 ->
- Just $ 100 * aquantity a1 / aquantity a2
- _ -> Nothing
- where
- toCost = normaliseMixedAmount . costOfMixedAmount
-
- showamt :: MixedAmount -> String
- showamt | color_ opts = cshowMixedAmountOneLineWithoutPrice
- | otherwise = showMixedAmountOneLineWithoutPrice
-
- -- Combine a table of actual amounts and a table of budgeted amounts into
- -- a single table of (Maybe actualamount, Maybe budgetamount) tuples.
- -- The actual and budget table need not have the same account rows or date columns.
- -- Every row and column from either table will appear in the combined table.
- -- TODO better to combine the reports, not these tables which are just rendering helpers
- combineTables :: ActualAmountsTable -> BudgetAmountsTable -> ActualAndBudgetAmountsTable
- combineTables (Table aaccthdrs adatehdrs arows) (Table baccthdrs bdatehdrs brows) =
- addtotalrow $ Table caccthdrs cdatehdrs crows
- where
- [aaccts, adates, baccts, bdates] = map headerContents [aaccthdrs, adatehdrs, baccthdrs, bdatehdrs]
- -- combined account names
- -- TODO Can't sort these or things will fall apart.
- caccts = dbg2 "caccts" $ init $ (dbg2 "aaccts" $ filter (not . null) aaccts) `union` (dbg2 "baccts" baccts)
- caccthdrs = T.Group NoLine $ map Header $ caccts
- -- Actual column dates and budget column dates could be different.
- -- TODO Can't easily combine these preserving correct order, will go wrong on monthly reports probably.
- cdates = dbg2 "cdates" $ sort $ (dbg2 "adates" adates) `union` (dbg2 "bdates" bdates)
- cdatehdrs = T.Group NoLine $ map Header cdates
- -- corresponding rows of combined actual and/or budget amounts
- crows = [ combineRow (actualRow a) (budgetRow a) | a <- caccts ]
- -- totals row
- addtotalrow | no_total_ opts = id
- | otherwise = (+----+ (row "" $ combineRow (actualRow "") (budgetRow "")))
- -- helpers
- combineRow arow brow =
- dbg1 "row" $ [(actualAmt d, budgetAmt d) | d <- cdates]
- where
- actualAmt date = Map.lookup date $ Map.fromList $ zip adates arow
- budgetAmt date = Map.lookup date $ Map.fromList $ zip bdates brow
-
- actualRow acct = fromMaybe [] $ Map.lookup acct $ Map.fromList $ zip aaccts arows
- budgetRow acct = fromMaybe [] $ Map.lookup acct $ Map.fromList $ zip baccts brows
-
--- | Given a table representing a multi-column balance report (for example,
--- made using 'balanceReportAsTable'), render it in a format suitable for
--- console output.
-renderBalanceReportTable :: ReportOpts -> Table String String MixedAmount -> String
-renderBalanceReportTable ropts =
- renderBalanceReportTable' ropts showamt
- where
- showamt | color_ ropts = cshowMixedAmountOneLineWithoutPrice
- | otherwise = showMixedAmountOneLineWithoutPrice
-
-renderBalanceReportTable' :: ReportOpts -> (a -> String) -> Table String String a -> String
-renderBalanceReportTable' (ReportOpts { pretty_tables_ = pretty}) showamt =
- unlines
- . trimborder
- . lines
- . render pretty id id showamt
- . align
- where
- trimborder = drop 1 . init . map (drop 1 . init)
- align (Table l t d) = Table l' t d
- where
- acctswidth = maximum' $ map strWidth (headerContents l)
- l' = padRightWide acctswidth <$> l
-
-- | Build a 'Table' from a multi-column balance report.
balanceReportAsTable :: ReportOpts -> MultiBalanceReport -> Table String String MixedAmount
balanceReportAsTable opts (MultiBalanceReport (colspans, items, (coltotals,tot,avg))) =
- addtotalrow $ Table
+ addtotalrow $
+ Table
(T.Group NoLine $ map Header accts)
(T.Group NoLine $ map Header colheadings)
(map rowvals items)
@@ -796,10 +636,14 @@ balanceReportAsTable opts (MultiBalanceReport (colspans, items, (coltotals,tot,a
++ (if average_ opts && not (null coltotals) then [avg] else [])
))
--- | Figure out the overall date span of a multicolumn balance report.
-multiBalanceReportSpan :: MultiBalanceReport -> DateSpan
-multiBalanceReportSpan (MultiBalanceReport ([], _, _)) = DateSpan Nothing Nothing
-multiBalanceReportSpan (MultiBalanceReport (colspans, _, _)) = DateSpan (spanStart $ head colspans) (spanEnd $ last colspans)
+-- | Given a table representing a multi-column balance report (for example,
+-- made using 'balanceReportAsTable'), render it in a format suitable for
+-- console output.
+balanceReportTableAsText :: ReportOpts -> Table String String MixedAmount -> String
+balanceReportTableAsText ropts = tableAsText ropts showamt
+ where
+ showamt | color_ ropts = cshowMixedAmountOneLineWithoutPrice
+ | otherwise = showMixedAmountOneLineWithoutPrice
tests_Hledger_Cli_Commands_Balance = TestList
diff --git a/Hledger/Cli/Commands/Import.hs b/Hledger/Cli/Commands/Import.hs
index d4b3da2..8d39860 100755
--- a/Hledger/Cli/Commands/Import.hs
+++ b/Hledger/Cli/Commands/Import.hs
@@ -44,7 +44,7 @@ importcmd opts@CliOpts{rawopts_=rawopts,inputopts_=iopts} j = do
case inputfiles of
[] -> error' "please provide one or more input files as arguments"
fs -> do
- enewj <- readJournalFilesWithOpts iopts' fs
+ enewj <- readJournalFiles iopts' fs
case enewj of
Left e -> error' e
Right newj ->
@@ -57,4 +57,4 @@ importcmd opts@CliOpts{rawopts_=rawopts,inputopts_=iopts} j = do
mapM_ (putStr . showTransactionUnelided) newts
newts -> do
foldM (flip journalAddTransaction opts) j newts -- gets forced somehow.. (how ?)
- printf "imported %d new transactions\n" (length newts) \ No newline at end of file
+ printf "imported %d new transactions\n" (length newts)
diff --git a/Hledger/Cli/CompoundBalanceCommand.hs b/Hledger/Cli/CompoundBalanceCommand.hs
index 73777fa..aea87af 100644
--- a/Hledger/Cli/CompoundBalanceCommand.hs
+++ b/Hledger/Cli/CompoundBalanceCommand.hs
@@ -249,7 +249,7 @@ Balance Sheet
compoundBalanceReportAsText :: ReportOpts -> CompoundBalanceReport -> String
compoundBalanceReportAsText ropts (title, _colspans, subreports, (coltotals, grandtotal, grandavg)) =
title ++ "\n\n" ++
- renderBalanceReportTable ropts bigtable'
+ balanceReportTableAsText ropts bigtable'
where
singlesubreport = length subreports == 1
bigtable =
diff --git a/Hledger/Cli/Main.hs b/Hledger/Cli/Main.hs
index a0a1b16..ec870fe 100644
--- a/Hledger/Cli/Main.hs
+++ b/Hledger/Cli/Main.hs
@@ -19,7 +19,7 @@ You can use the command line:
or ghci:
> $ ghci hledger
-> > j <- readJournalFile Nothing Nothing True "examples/sample.journal"
+> > j <- readJournalFile def "examples/sample.journal"
> > register [] ["income","expenses"] j
> 2008/01/01 income income:salary $-1 $-1
> 2008/06/01 gift income:gifts $-1 $-2
diff --git a/Hledger/Cli/Utils.hs b/Hledger/Cli/Utils.hs
index 8f272e5..31e78ac 100644
--- a/Hledger/Cli/Utils.hs
+++ b/Hledger/Cli/Utils.hs
@@ -57,8 +57,6 @@ import Hledger.Data
import Hledger.Read
import Hledger.Reports
import Hledger.Utils
-import Hledger.Query (Query(Any))
-
-- | Parse the user's specified journal file, maybe apply some transformations
-- (aliases, pivot) and run a hledger command on it, or throw an error.
@@ -68,14 +66,12 @@ withJournalDo opts cmd = do
-- it's stdin, or it doesn't exist and we are adding. We read it strictly
-- to let the add command work.
journalpaths <- journalFilePathFromOpts opts
- ej <- readJournalFilesWithOpts (inputopts_ opts) journalpaths
+ ej <- readJournalFiles (inputopts_ opts) journalpaths
let f = cmd opts
. pivotByOpts opts
. anonymiseByOpts opts
- . journalApplyAliases (aliasesFromOpts opts)
<=< journalApplyValue (reportopts_ opts)
<=< journalAddForecast opts
- . generateAutomaticPostings (reportopts_ opts)
either error' f ej
-- | Apply the pivot transformation on a journal, if option is present.
@@ -147,15 +143,6 @@ journalAddForecast opts j = do
in
either error' id $ journalBalanceTransactions assrt j
--- | Generate Automatic postings and add them to the current journal.
-generateAutomaticPostings :: ReportOpts -> Journal -> Journal
-generateAutomaticPostings ropts j =
- if auto_ ropts then j { jtxns = map modifier $ jtxns j } else j
- where
- modifier = foldr (flip (.) . runModifierTransaction') id mtxns
- runModifierTransaction' = fmap txnTieKnot . runModifierTransaction Any
- mtxns = jmodifiertxns j
-
-- | Write some output to stdout or to a file selected by --output-file.
-- If the file exists it will be overwritten.
writeOutput :: CliOpts -> String -> IO ()
@@ -164,8 +151,8 @@ writeOutput opts s = do
(if f == "-" then putStr else writeFile f) s
-- -- | Get a journal from the given string and options, or throw an error.
--- readJournalWithOpts :: CliOpts -> String -> IO Journal
--- readJournalWithOpts opts s = readJournal Nothing Nothing Nothing s >>= either error' return
+-- readJournal :: CliOpts -> String -> IO Journal
+-- readJournal opts s = readJournal def Nothing s >>= either error' return
-- | Re-read the journal file(s) specified by options and maybe apply some
-- transformations (aliases, pivot), or return an error string.
@@ -173,8 +160,8 @@ writeOutput opts s = do
journalReload :: CliOpts -> IO (Either String Journal)
journalReload opts = do
journalpaths <- journalFilePathFromOpts opts
- ((pivotByOpts opts . journalApplyAliases (aliasesFromOpts opts)) <$>) <$>
- readJournalFilesWithOpts (inputopts_ opts) journalpaths
+ (pivotByOpts opts <$>) <$>
+ readJournalFiles (inputopts_ opts) journalpaths
-- | Re-read the option-specified journal file(s), but only if any of
-- them has changed since last read. (If the file is standard input,
diff --git a/Text/Tabular/AsciiWide.hs b/Text/Tabular/AsciiWide.hs
deleted file mode 100644
index 60733cf..0000000
--- a/Text/Tabular/AsciiWide.hs
+++ /dev/null
@@ -1,111 +0,0 @@
--- | Text.Tabular.AsciiArt from tabular-0.2.2.7, modified to treat
--- wide characters as double width.
-
-module Text.Tabular.AsciiWide where
-
-import Data.List (intersperse, transpose)
-import Text.Tabular
-import Hledger.Utils.String
-
--- | for simplicity, we assume that each cell is rendered
--- on a single line
-render :: Bool -- ^ pretty tables
- -> (rh -> String)
- -> (ch -> String)
- -> (a -> String)
- -> Table rh ch a
- -> String
-render pretty fr fc f (Table rh ch cells) =
- unlines $ [ bar SingleLine -- +--------------------------------------+
- , renderColumns pretty sizes ch2
- , bar DoubleLine -- +======================================+
- ] ++
- (renderRs $ fmap renderR $ zipHeader [] cells $ fmap fr rh) ++
- [ bar SingleLine ] -- +--------------------------------------+
- where
- bar = concat . renderHLine pretty sizes ch2
- -- ch2 and cell2 include the row and column labels
- ch2 = Group DoubleLine [Header "", fmap fc ch]
- cells2 = headerContents ch2
- : zipWith (\h cs -> h : map f cs) rhStrings cells
- --
- renderR (cs,h) = renderColumns pretty sizes $ Group DoubleLine
- [ Header h
- , fmap fst $ zipHeader "" (map f cs) ch]
- rhStrings = map fr $ headerContents rh
- -- maximum width for each column
- sizes = map (maximum . map strWidth) . transpose $ cells2
- renderRs (Header s) = [s]
- renderRs (Group p hs) = concat . intersperse sep . map renderRs $ hs
- where sep = renderHLine pretty sizes ch2 p
-
-verticalBar :: Bool -> Char
-verticalBar pretty = if pretty then '│' else '|'
-
-leftBar :: Bool -> String
-leftBar pretty = verticalBar pretty : " "
-
-rightBar :: Bool -> String
-rightBar pretty = " " ++ [verticalBar pretty]
-
-midBar :: Bool -> String
-midBar pretty = " " ++ verticalBar pretty : " "
-
-doubleMidBar :: Bool -> String
-doubleMidBar pretty = if pretty then " ║ " else " || "
-
-horizontalBar :: Bool -> Char
-horizontalBar pretty = if pretty then '─' else '-'
-
-doubleHorizontalBar :: Bool -> Char
-doubleHorizontalBar pretty = if pretty then '═' else '='
-
--- | We stop rendering on the shortest list!
-renderColumns :: Bool -- ^ pretty
- -> [Int] -- ^ max width for each column
- -> Header String
- -> String
-renderColumns pretty is h = leftBar pretty ++ coreLine ++ rightBar pretty
- where
- coreLine = concatMap helper $ flattenHeader $ zipHeader 0 is h
- helper = either hsep (uncurry padLeftWide)
- hsep :: Properties -> String
- hsep NoLine = " "
- hsep SingleLine = midBar pretty
- hsep DoubleLine = doubleMidBar pretty
-
-renderHLine :: Bool -- ^ pretty
- -> [Int] -- ^ width specifications
- -> Header String
- -> Properties
- -> [String]
-renderHLine _ _ _ NoLine = []
-renderHLine pretty w h SingleLine = [renderHLine' pretty SingleLine w (horizontalBar pretty) h]
-renderHLine pretty w h DoubleLine = [renderHLine' pretty DoubleLine w (doubleHorizontalBar pretty) h]
-
-doubleCross :: Bool -> String
-doubleCross pretty = if pretty then "╬" else "++"
-
-doubleVerticalCross :: Bool -> String
-doubleVerticalCross pretty = if pretty then "╫" else "++"
-
-cross :: Bool -> Char
-cross pretty = if pretty then '┼' else '+'
-
-renderHLine' :: Bool -> Properties -> [Int] -> Char -> Header String -> String
-renderHLine' pretty prop is sep h = [ cross pretty, sep ] ++ coreLine ++ [sep, cross pretty]
- where
- coreLine = concatMap helper $ flattenHeader $ zipHeader 0 is h
- helper = either vsep dashes
- dashes (i,_) = replicate i sep
- vsep NoLine = replicate 2 sep -- match the double space sep in renderColumns
- vsep SingleLine = sep : cross pretty : [sep]
- vsep DoubleLine = sep : cross' ++ [sep]
- cross' = case prop of
- DoubleLine -> doubleCross pretty
- _ -> doubleVerticalCross pretty
-
--- padLeft :: Int -> String -> String
--- padLeft l s = padding ++ s
--- where padding = replicate (l - length s) ' '
-
diff --git a/bench/bench.hs b/bench/bench.hs
index 37c24f1..3df512a 100644
--- a/bench/bench.hs
+++ b/bench/bench.hs
@@ -4,6 +4,7 @@
import Criterion.Main (defaultMainWith, defaultConfig, bench, nfIO)
-- import QuickBench (defaultMain)
+import Data.Default
import System.Directory (getCurrentDirectory)
import System.Environment (getArgs, withArgs)
import System.TimeIt (timeItT)
@@ -33,7 +34,7 @@ main = do
benchWithTimeit = do
getCurrentDirectory >>= printf "Benchmarking hledger in %s with timeit\n"
let opts = defcliopts{output_file_=Just outputfile}
- (t0,j) <- timeit ("read "++inputfile) $ either error id <$> readJournalFile Nothing Nothing True inputfile
+ (t0,j) <- timeit ("read "++inputfile) $ either error id <$> readJournalFile def inputfile
(t1,_) <- timeit ("print") $ print' opts j
(t2,_) <- timeit ("register") $ register opts j
(t3,_) <- timeit ("balance") $ balance opts j
@@ -49,9 +50,9 @@ timeit name action = do
benchWithCriterion = do
getCurrentDirectory >>= printf "Benchmarking hledger in %s with criterion\n"
let opts = defcliopts{output_file_=Just "/dev/null"}
- j <- either error id <$> readJournalFile Nothing Nothing True inputfile
+ j <- either error id <$> readJournalFile def inputfile
Criterion.Main.defaultMainWith defaultConfig $ [
- bench ("read "++inputfile) $ nfIO $ (either error const <$> readJournalFile Nothing Nothing True inputfile),
+ bench ("read "++inputfile) $ nfIO $ (either error const <$> readJournalFile def inputfile),
bench ("print") $ nfIO $ print' opts j,
bench ("register") $ nfIO $ register opts j,
bench ("balance") $ nfIO $ balance opts j,
diff --git a/embeddedfiles/hledger-api.1 b/embeddedfiles/hledger-api.1
index cd408b6..331b95c 100644
--- a/embeddedfiles/hledger-api.1
+++ b/embeddedfiles/hledger-api.1
@@ -1,5 +1,5 @@
-.TH "hledger\-api" "1" "March 2018" "hledger\-api 1.9" "hledger User Manuals"
+.TH "hledger\-api" "1" "April 2018" "hledger\-api 1.9.1" "hledger User Manuals"
diff --git a/embeddedfiles/hledger-api.info b/embeddedfiles/hledger-api.info
index aaa1cee..f606b0f 100644
--- a/embeddedfiles/hledger-api.info
+++ b/embeddedfiles/hledger-api.info
@@ -3,8 +3,8 @@ This is hledger-api.info, produced by makeinfo version 6.5 from stdin.

File: hledger-api.info, Node: Top, Next: OPTIONS, Up: (dir)
-hledger-api(1) hledger-api 1.9
-******************************
+hledger-api(1) hledger-api 1.9.1
+********************************
hledger-api is a simple web API server, intended to support client-side
web apps operating on hledger data. It comes with a series of simple
@@ -80,7 +80,7 @@ options as shown above.

Tag Table:
Node: Top72
-Node: OPTIONS1658
-Ref: #options1743
+Node: OPTIONS1662
+Ref: #options1747

End Tag Table
diff --git a/embeddedfiles/hledger-api.txt b/embeddedfiles/hledger-api.txt
index eaec24f..fdbcddb 100644
--- a/embeddedfiles/hledger-api.txt
+++ b/embeddedfiles/hledger-api.txt
@@ -117,4 +117,4 @@ SEE ALSO
-hledger-api 1.9 March 2018 hledger-api(1)
+hledger-api 1.9.1 April 2018 hledger-api(1)
diff --git a/embeddedfiles/hledger-ui.1 b/embeddedfiles/hledger-ui.1
index d7a1a56..4a38db8 100644
--- a/embeddedfiles/hledger-ui.1
+++ b/embeddedfiles/hledger-ui.1
@@ -1,5 +1,5 @@
-.TH "hledger\-ui" "1" "March 2018" "hledger\-ui 1.9" "hledger User Manuals"
+.TH "hledger\-ui" "1" "April 2018" "hledger\-ui 1.9.1" "hledger User Manuals"
diff --git a/embeddedfiles/hledger-ui.info b/embeddedfiles/hledger-ui.info
index b2ff84a..27967d3 100644
--- a/embeddedfiles/hledger-ui.info
+++ b/embeddedfiles/hledger-ui.info
@@ -3,8 +3,8 @@ This is hledger-ui.info, produced by makeinfo version 6.5 from stdin.

File: hledger-ui.info, Node: Top, Next: OPTIONS, Up: (dir)
-hledger-ui(1) hledger-ui 1.9
-****************************
+hledger-ui(1) hledger-ui 1.9.1
+******************************
hledger-ui is hledger's curses-style interface, providing an efficient
full-window text UI for viewing accounts and transactions, and some
@@ -377,19 +377,19 @@ to cancel the reload attempt.)

Tag Table:
Node: Top71
-Node: OPTIONS821
-Ref: #options918
-Node: KEYS4135
-Ref: #keys4230
-Node: SCREENS7189
-Ref: #screens7274
-Node: Accounts screen7364
-Ref: #accounts-screen7492
-Node: Register screen9722
-Ref: #register-screen9877
-Node: Transaction screen11951
-Ref: #transaction-screen12109
-Node: Error screen12979
-Ref: #error-screen13101
+Node: OPTIONS825
+Ref: #options922
+Node: KEYS4139
+Ref: #keys4234
+Node: SCREENS7193
+Ref: #screens7278
+Node: Accounts screen7368
+Ref: #accounts-screen7496
+Node: Register screen9726
+Ref: #register-screen9881
+Node: Transaction screen11955
+Ref: #transaction-screen12113
+Node: Error screen12983
+Ref: #error-screen13105

End Tag Table
diff --git a/embeddedfiles/hledger-ui.txt b/embeddedfiles/hledger-ui.txt
index 856d91a..8a310cb 100644
--- a/embeddedfiles/hledger-ui.txt
+++ b/embeddedfiles/hledger-ui.txt
@@ -384,4 +384,4 @@ SEE ALSO
-hledger-ui 1.9 March 2018 hledger-ui(1)
+hledger-ui 1.9.1 April 2018 hledger-ui(1)
diff --git a/embeddedfiles/hledger-web.1 b/embeddedfiles/hledger-web.1
index 1911cba..09c1f70 100644
--- a/embeddedfiles/hledger-web.1
+++ b/embeddedfiles/hledger-web.1
@@ -1,5 +1,5 @@
-.TH "hledger\-web" "1" "March 2018" "hledger\-web 1.9" "hledger User Manuals"
+.TH "hledger\-web" "1" "April 2018" "hledger\-web 1.9.1" "hledger User Manuals"
diff --git a/embeddedfiles/hledger-web.info b/embeddedfiles/hledger-web.info
index d82aa1d..0be780d 100644
--- a/embeddedfiles/hledger-web.info
+++ b/embeddedfiles/hledger-web.info
@@ -3,8 +3,8 @@ This is hledger-web.info, produced by makeinfo version 6.5 from stdin.

File: hledger-web.info, Node: Top, Next: OPTIONS, Up: (dir)
-hledger-web(1) hledger-web 1.9
-******************************
+hledger-web(1) hledger-web 1.9.1
+********************************
hledger-web is hledger's web interface. It starts a simple web
application for browsing and adding transactions, and optionally opens
@@ -209,7 +209,7 @@ this, insert a '--' argument before.)

Tag Table:
Node: Top72
-Node: OPTIONS3152
-Ref: #options3237
+Node: OPTIONS3156
+Ref: #options3241

End Tag Table
diff --git a/embeddedfiles/hledger-web.txt b/embeddedfiles/hledger-web.txt
index 4373881..79244ea 100644
--- a/embeddedfiles/hledger-web.txt
+++ b/embeddedfiles/hledger-web.txt
@@ -248,4 +248,4 @@ SEE ALSO
-hledger-web 1.9 March 2018 hledger-web(1)
+hledger-web 1.9.1 April 2018 hledger-web(1)
diff --git a/embeddedfiles/hledger.1 b/embeddedfiles/hledger.1
index c4c2e6d..7f6ff87 100644
--- a/embeddedfiles/hledger.1
+++ b/embeddedfiles/hledger.1
@@ -1,6 +1,6 @@
.\"t
-.TH "hledger" "1" "March 2018" "hledger 1.9" "hledger User Manuals"
+.TH "hledger" "1" "April 2018" "hledger 1.9.1" "hledger User Manuals"
@@ -1096,13 +1096,11 @@ The following kinds of search terms can be used.
Remember these can also be prefixed with \f[B]\f[BC]not:\f[B]\f[], eg to
exclude a particular subaccount.
.TP
-.B \f[B]\f[BC]REGEX\f[B]\f[]
+.B \f[B]\f[BC]REGEX\f[B], \f[BC]acct:REGEX\f[B]\f[]
match account names by this regular expression.
-(No prefix is equivalent to \f[C]acct:\f[]).
+(With no prefix, \f[C]acct:\f[] is assumed.)
.RS
.RE
-.TP
-.B \f[B]\f[BC]acct:REGEX\f[B]\f[]
same as above
.RS
.RE
@@ -1514,8 +1512,35 @@ with \[en]budget, show unbudgeted accounts also
.RS
.RE
.PP
-The balance command displays accounts and balances.
-It is hledger's most featureful and versatile command.
+The balance command is hledger's most versatile command.
+Note, despite the name, it is not always used for showing real\-world
+account balances; the more accounting\-aware balancesheet and
+incomestatement may be more convenient for that.
+.PP
+By default, it displays all accounts, and each account's change in
+balance during the entire period of the journal.
+Balance changes are calculated by adding up the postings in each
+account.
+You can limit the postings matched, by a query, to see fewer accounts,
+changes over a different time period, changes from only cleared
+transactions, etc.
+.PP
+If you include an account's complete history of postings in the report,
+the balance change is equivalent to the account's current ending
+balance.
+For a real\-world account, typically you won't have all transactions in
+the journal; instead you'll have all transactions after a certain date,
+and an \[lq]opening balances\[rq] transaction setting the correct
+starting balance on that date.
+Then the balance command will show real\-world account balances.
+In some cases the \-H/\[en]historical flag is used to ensure this (more
+below).
+.PP
+The balance command can produce several styles of report:
+.SS Classic balance report
+.PP
+This is the original balance report, as found in Ledger.
+It usually looks like this:
.IP
.nf
\f[C]
@@ -1535,12 +1560,6 @@ $\ hledger\ balance
\f[]
.fi
.PP
-More precisely, the balance command shows the \f[I]change\f[] to each
-account's balance caused by all (matched) postings.
-In the common case where you do not filter by date and your journal sets
-the correct opening balances, this is the same as the account's ending
-balance.
-.PP
By default, accounts are displayed hierarchically, with subaccounts
indented below their parent.
At each level of the tree, accounts are sorted by account code if any,
@@ -1550,8 +1569,8 @@ Or with \f[C]\-S/\-\-sort\-amount\f[], by their balance amount.
\[lq]Boring\[rq] accounts, which contain a single interesting subaccount
and no balance of their own, are elided into the following line for more
compact output.
-(Not yet supported in tabular reports.) Use \f[C]\-\-no\-elide\f[] to
-prevent this.
+(Eg above, the \[lq]liabilities\[rq] account.) Use
+\f[C]\-\-no\-elide\f[] to prevent this.
.PP
Account balances are \[lq]inclusive\[rq] \- they include the balances of
any subaccounts.
@@ -1561,7 +1580,7 @@ omitted.
Use \f[C]\-E/\-\-empty\f[] to show them.
.PP
A final total is displayed by default; use \f[C]\-N/\-\-no\-total\f[] to
-suppress it:
+suppress it, eg:
.IP
.nf
\f[C]
@@ -1571,11 +1590,89 @@ $\ hledger\ balance\ \-p\ 2008/6\ expenses\ \-\-no\-total
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ supplies
\f[]
.fi
+.SS Customising the classic balance report
+.PP
+You can customise the layout of classic balance reports with
+\f[C]\-\-format\ FMT\f[]:
+.IP
+.nf
+\f[C]
+$\ hledger\ 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
+\f[]
+.fi
+.PP
+The FMT format string (plus a newline) specifies the formatting applied
+to each account/balance pair.
+It may contain any suitable text, with data fields interpolated like so:
+.PP
+\f[C]%[MIN][.MAX](FIELDNAME)\f[]
+.IP \[bu] 2
+MIN pads with spaces to at least this width (optional)
+.IP \[bu] 2
+MAX truncates at this width (optional)
+.IP \[bu] 2
+FIELDNAME must be enclosed in parentheses, and can be one of:
+.RS 2
+.IP \[bu] 2
+\f[C]depth_spacer\f[] \- a number of spaces equal to the account's
+depth, or if MIN is specified, MIN * depth spaces.
+.IP \[bu] 2
+\f[C]account\f[] \- the account's name
+.IP \[bu] 2
+\f[C]total\f[] \- the account's balance/posted total, right justified
+.RE
+.PP
+Also, FMT can begin with an optional prefix to control how
+multi\-commodity amounts are rendered:
+.IP \[bu] 2
+\f[C]%_\f[] \- render on multiple lines, bottom\-aligned (the default)
+.IP \[bu] 2
+\f[C]%^\f[] \- render on multiple lines, top\-aligned
+.IP \[bu] 2
+\f[C]%,\f[] \- render on one line, comma\-separated
+.PP
+There are some quirks.
+Eg in one\-line mode, \f[C]%(depth_spacer)\f[] has no effect, instead
+\f[C]%(account)\f[] has indentation built in.
+ Experimentation may be needed to get pleasing results.
+.PP
+Some example formats:
+.IP \[bu] 2
+\f[C]%(total)\f[] \- the account's total
+.IP \[bu] 2
+\f[C]%\-20.20(account)\f[] \- the account's name, left justified, padded
+to 20 characters and clipped at 20 characters
+.IP \[bu] 2
+\f[C]%,%\-50(account)\ \ %25(total)\f[] \- account name padded to 50
+characters, total padded to 20 characters, with multiple commodities
+rendered on one line
+.IP \[bu] 2
+\f[C]%20(total)\ \ %2(depth_spacer)%\-(account)\f[] \- the default
+format for the single\-column balance report
+.SS Colour support
+.PP
+The balance command shows negative amounts in red, if:
+.IP \[bu] 2
+the \f[C]TERM\f[] environment variable is not set to \f[C]dumb\f[]
+.IP \[bu] 2
+the output is not being redirected or piped anywhere
.SS Flat mode
.PP
-To see a flat list of full account names instead of the default
-hierarchical display, use \f[C]\-\-flat\f[].
-In this mode, accounts (unless depth\-clipped) show their
+To see a flat list instead of the default hierarchical display, use
+\f[C]\-\-flat\f[].
+In this mode, accounts (unless depth\-clipped) show their full names and
\[lq]exclusive\[rq] balance, excluding any subaccount balances.
In this mode, you can also use \f[C]\-\-drop\ N\f[] to omit the first
few account name components.
@@ -1589,26 +1686,32 @@ $\ hledger\ balance\ \-p\ 2008/6\ expenses\ \-N\ \-\-flat\ \-\-drop\ 1
.fi
.SS Depth limited balance reports
.PP
-With \f[C]\-\-depth\ N\f[], balance shows accounts only to the specified
-depth.
-This is very useful to show a complex charts of accounts in less detail.
-In flat mode, balances from accounts below the depth limit will be shown
-as part of a parent account at the depth limit.
+With \f[C]\-\-depth\ N\f[] or \f[C]depth:N\f[] or just \f[C]\-N\f[],
+balance reports show accounts only to the specified numeric depth.
+This is very useful to summarise a complex set of accounts and get an
+overview.
.IP
.nf
\f[C]
-$\ hledger\ balance\ \-N\ \-\-depth\ 1
+$\ hledger\ balance\ \-N\ \-1
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ income
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities
\f[]
.fi
-.SS Multicolumn balance reports
.PP
-With a reporting interval, multiple balance columns will be shown, one
-for each report period.
-There are three types of multi\-column balance report, showing different
+Flat\-mode balance reports, which normally show exclusive balances, show
+inclusive balances at the depth limit.
+.SS Multicolumn balance report
+.PP
+Multicolumn or tabular balance reports are a very useful hledger
+feature, and usually the preferred style.
+They share many of the above features, but they show the report as a
+table, with columns representing time periods.
+This mode is activated by providing a reporting interval.
+.PP
+There are three types of multicolumn balance report, showing different
information:
.IP "1." 3
By default: each column shows the sum of postings in that period, ie the
@@ -1680,8 +1783,8 @@ Ending\ balances\ (historical)\ in\ 2008/04/01\-2008/12/31:
.fi
.RE
.PP
-Multi\-column balance reports display accounts in flat mode by default;
-to see the hierarchy, use \f[C]\-\-tree\f[].
+Multicolumn balance reports display accounts in flat mode by default; to
+see the hierarchy, use \f[C]\-\-tree\f[].
.PP
With a reporting interval (like \f[C]\-\-quarterly\f[] above), the
report start/end dates will be adjusted if necessary so that they
@@ -1725,13 +1828,23 @@ Balance\ changes\ in\ 2008:
#\ Average\ is\ rounded\ to\ the\ dollar\ here\ since\ all\ journal\ amounts\ are
\f[]
.fi
-.SS Budgets
.PP
-With \f[C]\-\-budget\f[] and a report interval, all periodic
-transactions in your journal with that interval, active during the
-requested report period, are interpreted as recurring budget goals for
-the specified accounts (and subaccounts), and the report will show the
-difference between actual and budgeted balances.
+Limitations:
+.PP
+In multicolumn reports the \f[C]\-V/\-\-value\f[] flag uses the market
+price on the report end date, for all columns (not the price on each
+column's end date).
+.PP
+Eliding of boring parent accounts in tree mode, as in the classic
+balance report, is not yet supported in multicolumn reports.
+.SS Budget report
+.PP
+With \f[C]\-\-budget\f[], extra columns are displayed showing budget
+goals for each account and period, if any.
+Budget goals are defined by periodic transactions.
+This is very useful for comparing planned and actual income, expenses,
+time usage, etc.
+\[en]budget is most often combined with a report interval.
.PP
For example, you can take average monthly expenses in the common expense
categories to construct a minimal monthly budget:
@@ -1764,156 +1877,61 @@ categories to construct a minimal monthly budget:
\f[]
.fi
.PP
-You can now see a monthly budget performance report:
+You can now see a monthly budget report:
.IP
.nf
\f[C]
$\ hledger\ balance\ \-M\ \-\-budget
-Balance\ changes\ in\ 2017/11/01\-2017/12/31:
-
-\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12\
-=======================++=================================================
-\ <unbudgeted>:expenses\ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $100\
-\ assets:bank:checking\ \ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-2665\ [107%\ of\ $\-2480]\
-\ expenses:bus\ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ \ \ $53\ [106%\ of\ $50]\
-\ expenses:food\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $412\ [103%\ of\ $400]\
-\ expenses:movies\ \ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ \ \ \ 0\ [0%\ of\ $30]\
-\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $2100\ [105%\ of\ $2000]\
-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
-\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\
-\f[]
-.fi
-.PP
-You can roll over unspent budgets to next period with
-\f[C]\-\-cumulative\f[]:
-.IP
-.nf
-\f[C]
-$\ hledger\ balance\ \-M\ \-\-budget\ \-\-cumulative
-Ending\ balances\ (cumulative)\ in\ 2017/11/01\-2017/12/31:
-
-\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11/30\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12/31\
-=======================++=================================================
-\ <unbudgeted>:expenses\ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $120\
-\ assets:bank:checking\ \ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-5110\ [103%\ of\ $\-4960]\
-\ expenses:bus\ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ $102\ [102%\ of\ $100]\
-\ expenses:food\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $808\ [101%\ of\ $800]\
-\ expenses:movies\ \ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ $30\ [50%\ of\ $60]\
-\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $4050\ [101%\ of\ $4000]\
-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
-\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0
-\f[]
-.fi
-.PP
-Accounts with no budget goals (not mentioned in the periodic
-transactions) will be aggregated under \f[C]<unbudgeted>\f[], unless you
-add the \f[C]\-\-show\-unbudgeted\f[] flag to display them normally:
-.IP
-.nf
-\f[C]
-$\ hledger\ balance\ \-\-budget\ \-\-show\-unbudgeted
-Balance\ changes\ in\ 2017/11/01\-2017/12/31:
+Budget\ performance\ in\ 2017/11/01\-2017/12/31:
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12\
======================++=================================================
+\ <unbudgeted>\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $100\
\ assets:bank:checking\ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-2665\ [107%\ of\ $\-2480]\
\ expenses:bus\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ \ \ $53\ [106%\ of\ $50]\
\ expenses:food\ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $412\ [103%\ of\ $400]\
-\ expenses:gifts\ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $100\
\ expenses:movies\ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ \ \ \ 0\ [0%\ of\ $30]\
-\ expenses:supplies\ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\
\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $2100\ [105%\ of\ $2000]\
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\
\f[]
.fi
.PP
-Note \[en]budget first arrived in hledger in 1.5 and is still pretty
-young; join the discussions on mail list and issue tracker to help us
-refine it.
-.PP
-For more examples, see Budgeting and Forecasting.
-.SS Custom balance output
+By default, only accounts with budget goals during the report period are
+shown.
+\f[C]\-\-show\-unbudgeted\f[] shows unbudgeted accounts as well.
+Top\-level accounts with no budget goals anywhere below them are grouped
+under \f[C]<unbudgeted>\f[].
.PP
-You can customise the layout of simple (non\-tabular) balance reports
-with \f[C]\-\-format\ FMT\f[]:
+You can roll over unspent budgets to next period with
+\f[C]\-\-cumulative\f[]:
.IP
.nf
\f[C]
-$\ hledger\ 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
+$\ hledger\ balance\ \-M\ \-\-budget\ \-\-cumulative
+Budget\ performance\ in\ 2017/11/01\-2017/12/31:
+
+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11/30\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12/31\
+======================++=================================================
+\ <unbudgeted>\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $120\
+\ assets:bank:checking\ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-5110\ [103%\ of\ $\-4960]\
+\ expenses:bus\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ $102\ [102%\ of\ $100]\
+\ expenses:food\ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $808\ [101%\ of\ $800]\
+\ expenses:movies\ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ $30\ [50%\ of\ $60]\
+\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $4050\ [101%\ of\ $4000]\
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0
\f[]
.fi
.PP
-The FMT format string (plus a newline) specifies the formatting applied
-to each account/balance pair.
-It may contain any suitable text, with data fields interpolated like so:
+Note, the \f[C]\-S/\-\-sort\-amount\f[] flag is not yet fully supported
+with \f[C]\-\-budget\f[].
.PP
-\f[C]%[MIN][.MAX](FIELDNAME)\f[]
-.IP \[bu] 2
-MIN pads with spaces to at least this width (optional)
-.IP \[bu] 2
-MAX truncates at this width (optional)
-.IP \[bu] 2
-FIELDNAME must be enclosed in parentheses, and can be one of:
-.RS 2
-.IP \[bu] 2
-\f[C]depth_spacer\f[] \- a number of spaces equal to the account's
-depth, or if MIN is specified, MIN * depth spaces.
-.IP \[bu] 2
-\f[C]account\f[] \- the account's name
-.IP \[bu] 2
-\f[C]total\f[] \- the account's balance/posted total, right justified
-.RE
-.PP
-Also, FMT can begin with an optional prefix to control how
-multi\-commodity amounts are rendered:
-.IP \[bu] 2
-\f[C]%_\f[] \- render on multiple lines, bottom\-aligned (the default)
-.IP \[bu] 2
-\f[C]%^\f[] \- render on multiple lines, top\-aligned
-.IP \[bu] 2
-\f[C]%,\f[] \- render on one line, comma\-separated
-.PP
-There are some quirks.
-Eg in one\-line mode, \f[C]%(depth_spacer)\f[] has no effect, instead
-\f[C]%(account)\f[] has indentation built in.
- Experimentation may be needed to get pleasing results.
-.PP
-Some example formats:
-.IP \[bu] 2
-\f[C]%(total)\f[] \- the account's total
-.IP \[bu] 2
-\f[C]%\-20.20(account)\f[] \- the account's name, left justified, padded
-to 20 characters and clipped at 20 characters
-.IP \[bu] 2
-\f[C]%,%\-50(account)\ \ %25(total)\f[] \- account name padded to 50
-characters, total padded to 20 characters, with multiple commodities
-rendered on one line
-.IP \[bu] 2
-\f[C]%20(total)\ \ %2(depth_spacer)%\-(account)\f[] \- the default
-format for the single\-column balance report
+For more examples, see Budgeting and Forecasting.
+.SS Output format
.PP
-This command also supports output destination and output format
+The balance command supports output destination and output format
selection.
-.SS Colour support
-.PP
-The balance command shows negative amounts in red, if:
-.IP \[bu] 2
-the \f[C]TERM\f[] environment variable is not set to \f[C]dumb\f[]
-.IP \[bu] 2
-the output is not being redirected or piped anywhere
.SS balancesheet
.PP
This command displays a simple balance sheet, showing historical ending
diff --git a/embeddedfiles/hledger.info b/embeddedfiles/hledger.info
index ee48104..4b7caaa 100644
--- a/embeddedfiles/hledger.info
+++ b/embeddedfiles/hledger.info
@@ -3,8 +3,8 @@ This is hledger.info, produced by makeinfo version 6.5 from stdin.

File: hledger.info, Node: Top, Next: EXAMPLES, Up: (dir)
-hledger(1) hledger 1.9
-**********************
+hledger(1) hledger 1.9.1
+************************
This is hledger's command-line interface (there are also curses and web
interfaces). Its basic function is to read a plain text file describing
@@ -785,13 +785,11 @@ instead most commands show transactions/postings/accounts which match
The following kinds of search terms can be used. Remember these can
also be prefixed with *'not:'*, eg to exclude a particular subaccount.
-*'REGEX'*
+*'REGEX', 'acct:REGEX'*
- match account names by this regular expression. (No prefix is
- equivalent to 'acct:').
-*'acct:REGEX'*
+ match account names by this regular expression. (With no prefix,
+ 'acct:' is assumed.) same as above
- same as above
*'amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N'*
match postings with a single-commodity amount that is equal to,
@@ -1138,8 +1136,46 @@ Show accounts and their balances. Aliases: b, bal.
with -budget, show unbudgeted accounts also
- The balance command displays accounts and balances. It is hledger's
-most featureful and versatile command.
+ The balance command is hledger's most versatile command. Note,
+despite the name, it is not always used for showing real-world account
+balances; the more accounting-aware balancesheet and incomestatement may
+be more convenient for that.
+
+ By default, it displays all accounts, and each account's change in
+balance during the entire period of the journal. Balance changes are
+calculated by adding up the postings in each account. You can limit the
+postings matched, by a query, to see fewer accounts, changes over a
+different time period, changes from only cleared transactions, etc.
+
+ If you include an account's complete history of postings in the
+report, the balance change is equivalent to the account's current ending
+balance. For a real-world account, typically you won't have all
+transactions in the journal; instead you'll have all transactions after
+a certain date, and an "opening balances" transaction setting the
+correct starting balance on that date. Then the balance command will
+show real-world account balances. In some cases the -H/-historical flag
+is used to ensure this (more below).
+
+ The balance command can produce several styles of report:
+* Menu:
+
+* Classic balance report::
+* Customising the classic balance report::
+* Colour support::
+* Flat mode::
+* Depth limited balance reports::
+* Multicolumn balance report::
+* Budget report::
+* Output format::
+
+
+File: hledger.info, Node: Classic balance report, Next: Customising the classic balance report, Up: balance
+
+4.4.1 Classic balance report
+----------------------------
+
+This is the original balance report, as found in Ledger. It usually
+looks like this:
$ hledger balance
$-1 assets
@@ -1155,11 +1191,6 @@ $ hledger balance
--------------------
0
- More precisely, the balance command shows the _change_ to each
-account's balance caused by all (matched) postings. In the common case
-where you do not filter by date and your journal sets the correct
-opening balances, this is the same as the account's ending balance.
-
By default, accounts are displayed hierarchically, with subaccounts
indented below their parent. At each level of the tree, accounts are
sorted by account code if any, then by account name. Or with
@@ -1167,7 +1198,7 @@ sorted by account code if any, then by account name. Or with
"Boring" accounts, which contain a single interesting subaccount and
no balance of their own, are elided into the following line for more
-compact output. (Not yet supported in tabular reports.) Use
+compact output. (Eg above, the "liabilities" account.) Use
'--no-elide' to prevent this.
Account balances are "inclusive" - they include the balances of any
@@ -1177,64 +1208,132 @@ subaccounts.
omitted. Use '-E/--empty' to show them.
A final total is displayed by default; use '-N/--no-total' to
-suppress it:
+suppress it, eg:
$ hledger balance -p 2008/6 expenses --no-total
$2 expenses
$1 food
$1 supplies
-* Menu:
+
+File: hledger.info, Node: Customising the classic balance report, Next: Colour support, Prev: Classic balance report, Up: balance
-* Flat mode::
-* Depth limited balance reports::
-* Multicolumn balance reports::
-* Budgets::
-* Custom balance output::
-* Colour support::
+4.4.2 Customising the classic balance report
+--------------------------------------------
+
+You can customise the layout of classic balance reports with '--format
+FMT':
+
+$ hledger balance --format "%20(account) %12(total)"
+ assets $-1
+ bank:saving $1
+ cash $-2
+ expenses $2
+ food $1
+ supplies $1
+ income $-2
+ gifts $-1
+ salary $-1
+ liabilities:debts $1
+---------------------------------
+ 0
+
+ The FMT format string (plus a newline) specifies the formatting
+applied to each account/balance pair. It may contain any suitable text,
+with data fields interpolated like so:
+
+ '%[MIN][.MAX](FIELDNAME)'
+
+ * MIN pads with spaces to at least this width (optional)
+ * MAX truncates at this width (optional)
+ * FIELDNAME must be enclosed in parentheses, and can be one of:
+
+ * 'depth_spacer' - a number of spaces equal to the account's
+ depth, or if MIN is specified, MIN * depth spaces.
+ * 'account' - the account's name
+ * 'total' - the account's balance/posted total, right justified
+
+ Also, FMT can begin with an optional prefix to control how
+multi-commodity amounts are rendered:
+
+ * '%_' - render on multiple lines, bottom-aligned (the default)
+ * '%^' - render on multiple lines, top-aligned
+ * '%,' - render on one line, comma-separated
+
+ There are some quirks. Eg in one-line mode, '%(depth_spacer)' has no
+effect, instead '%(account)' has indentation built in. Experimentation
+may be needed to get pleasing results.
+
+ Some example formats:
+
+ * '%(total)' - the account's total
+ * '%-20.20(account)' - the account's name, left justified, padded to
+ 20 characters and clipped at 20 characters
+ * '%,%-50(account) %25(total)' - account name padded to 50
+ characters, total padded to 20 characters, with multiple
+ commodities rendered on one line
+ * '%20(total) %2(depth_spacer)%-(account)' - the default format for
+ the single-column balance report
+
+
+File: hledger.info, Node: Colour support, Next: Flat mode, Prev: Customising the classic balance report, Up: balance
+
+4.4.3 Colour support
+--------------------
+
+The balance command shows negative amounts in red, if:
+
+ * the 'TERM' environment variable is not set to 'dumb'
+ * the output is not being redirected or piped anywhere

-File: hledger.info, Node: Flat mode, Next: Depth limited balance reports, Up: balance
+File: hledger.info, Node: Flat mode, Next: Depth limited balance reports, Prev: Colour support, Up: balance
-4.4.1 Flat mode
+4.4.4 Flat mode
---------------
-To see a flat list of full account names instead of the default
-hierarchical display, use '--flat'. In this mode, accounts (unless
-depth-clipped) show their "exclusive" balance, excluding any subaccount
-balances. In this mode, you can also use '--drop N' to omit the first
-few account name components.
+To see a flat list instead of the default hierarchical display, use
+'--flat'. In this mode, accounts (unless depth-clipped) show their full
+names and "exclusive" balance, excluding any subaccount balances. In
+this mode, you can also use '--drop N' to omit the first few account
+name components.
$ hledger balance -p 2008/6 expenses -N --flat --drop 1
$1 food
$1 supplies

-File: hledger.info, Node: Depth limited balance reports, Next: Multicolumn balance reports, Prev: Flat mode, Up: balance
+File: hledger.info, Node: Depth limited balance reports, Next: Multicolumn balance report, Prev: Flat mode, Up: balance
-4.4.2 Depth limited balance reports
+4.4.5 Depth limited balance reports
-----------------------------------
-With '--depth N', balance shows accounts only to the specified depth.
-This is very useful to show a complex charts of accounts in less detail.
-In flat mode, balances from accounts below the depth limit will be shown
-as part of a parent account at the depth limit.
+With '--depth N' or 'depth:N' or just '-N', balance reports show
+accounts only to the specified numeric depth. This is very useful to
+summarise a complex set of accounts and get an overview.
-$ hledger balance -N --depth 1
+$ hledger balance -N -1
$-1 assets
$2 expenses
$-2 income
$1 liabilities
+ Flat-mode balance reports, which normally show exclusive balances,
+show inclusive balances at the depth limit.
+

-File: hledger.info, Node: Multicolumn balance reports, Next: Budgets, Prev: Depth limited balance reports, Up: balance
+File: hledger.info, Node: Multicolumn balance report, Next: Budget report, Prev: Depth limited balance reports, Up: balance
-4.4.3 Multicolumn balance reports
----------------------------------
+4.4.6 Multicolumn balance report
+--------------------------------
+
+Multicolumn or tabular balance reports are a very useful hledger
+feature, and usually the preferred style. They share many of the above
+features, but they show the report as a table, with columns representing
+time periods. This mode is activated by providing a reporting interval.
-With a reporting interval, multiple balance columns will be shown, one
-for each report period. There are three types of multi-column balance
-report, showing different information:
+ There are three types of multicolumn balance report, showing
+different information:
1. By default: each column shows the sum of postings in that period,
ie the account's change of balance in that period. This is useful
@@ -1286,8 +1385,8 @@ report, showing different information:
----------------------++-------------------------------------
|| 0 0 0
- Multi-column balance reports display accounts in flat mode by
-default; to see the hierarchy, use '--tree'.
+ Multicolumn balance reports display accounts in flat mode by default;
+to see the hierarchy, use '--tree'.
With a reporting interval (like '--quarterly' above), the report
start/end dates will be adjusted if necessary so that they encompass the
@@ -1326,17 +1425,26 @@ Balance changes in 2008:
# Average is rounded to the dollar here since all journal amounts are
+ Limitations:
+
+ In multicolumn reports the '-V/--value' flag uses the market price on
+the report end date, for all columns (not the price on each column's end
+date).
+
+ Eliding of boring parent accounts in tree mode, as in the classic
+balance report, is not yet supported in multicolumn reports.
+

-File: hledger.info, Node: Budgets, Next: Custom balance output, Prev: Multicolumn balance reports, Up: balance
+File: hledger.info, Node: Budget report, Next: , Prev: Multicolumn balance report, Up: balance
-4.4.4 Budgets
--------------
+4.4.7 Budget report
+-------------------
-With '--budget' and a report interval, all periodic transactions in your
-journal with that interval, active during the requested report period,
-are interpreted as recurring budget goals for the specified accounts
-(and subaccounts), and the report will show the difference between
-actual and budgeted balances.
+With '--budget', extra columns are displayed showing budget goals for
+each account and period, if any. Budget goals are defined by periodic
+transactions. This is very useful for comparing planned and actual
+income, expenses, time usage, etc. -budget is most often combined with
+a report interval.
For example, you can take average monthly expenses in the common
expense categories to construct a minimal monthly budget:
@@ -1365,138 +1473,55 @@ expense categories to construct a minimal monthly budget:
expenses:gifts $100
assets:bank:checking
- You can now see a monthly budget performance report:
+ You can now see a monthly budget report:
$ hledger balance -M --budget
-Balance changes in 2017/11/01-2017/12/31:
-
- || 2017/11 2017/12
-=======================++=================================================
- <unbudgeted>:expenses || $20 $100
- assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
- expenses:bus || $49 [98% of $50] $53 [106% of $50]
- expenses:food || $396 [99% of $400] $412 [103% of $400]
- expenses:movies || $30 [100% of $30] 0 [0% of $30]
- income || $1950 [98% of $2000] $2100 [105% of $2000]
------------------------++-------------------------------------------------
- || 0 0
-
- You can roll over unspent budgets to next period with '--cumulative':
-
-$ hledger balance -M --budget --cumulative
-Ending balances (cumulative) in 2017/11/01-2017/12/31:
-
- || 2017/11/30 2017/12/31
-=======================++=================================================
- <unbudgeted>:expenses || $20 $120
- assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960]
- expenses:bus || $49 [98% of $50] $102 [102% of $100]
- expenses:food || $396 [99% of $400] $808 [101% of $800]
- expenses:movies || $30 [100% of $30] $30 [50% of $60]
- income || $1950 [98% of $2000] $4050 [101% of $4000]
------------------------++-------------------------------------------------
- || 0 0
-
- Accounts with no budget goals (not mentioned in the periodic
-transactions) will be aggregated under '<unbudgeted>', unless you add
-the '--show-unbudgeted' flag to display them normally:
-
-$ hledger balance --budget --show-unbudgeted
-Balance changes in 2017/11/01-2017/12/31:
+Budget performance in 2017/11/01-2017/12/31:
|| 2017/11 2017/12
======================++=================================================
+ <unbudgeted> || $20 $100
assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
expenses:bus || $49 [98% of $50] $53 [106% of $50]
expenses:food || $396 [99% of $400] $412 [103% of $400]
- expenses:gifts || 0 $100
expenses:movies || $30 [100% of $30] 0 [0% of $30]
- expenses:supplies || $20 0
income || $1950 [98% of $2000] $2100 [105% of $2000]
----------------------++-------------------------------------------------
|| 0 0
- Note -budget first arrived in hledger in 1.5 and is still pretty
-young; join the discussions on mail list and issue tracker to help us
-refine it.
-
- For more examples, see Budgeting and Forecasting.
-
-
-File: hledger.info, Node: Custom balance output, Next: Colour support, Prev: Budgets, Up: balance
-
-4.4.5 Custom balance output
----------------------------
-
-You can customise the layout of simple (non-tabular) balance reports
-with '--format FMT':
-
-$ hledger balance --format "%20(account) %12(total)"
- assets $-1
- bank:saving $1
- cash $-2
- expenses $2
- food $1
- supplies $1
- income $-2
- gifts $-1
- salary $-1
- liabilities:debts $1
----------------------------------
- 0
-
- The FMT format string (plus a newline) specifies the formatting
-applied to each account/balance pair. It may contain any suitable text,
-with data fields interpolated like so:
-
- '%[MIN][.MAX](FIELDNAME)'
-
- * MIN pads with spaces to at least this width (optional)
- * MAX truncates at this width (optional)
- * FIELDNAME must be enclosed in parentheses, and can be one of:
+ By default, only accounts with budget goals during the report period
+are shown. '--show-unbudgeted' shows unbudgeted accounts as well.
+Top-level accounts with no budget goals anywhere below them are grouped
+under '<unbudgeted>'.
- * '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
+ You can roll over unspent budgets to next period with '--cumulative':
- Also, FMT can begin with an optional prefix to control how
-multi-commodity amounts are rendered:
+$ hledger balance -M --budget --cumulative
+Budget performance in 2017/11/01-2017/12/31:
- * '%_' - render on multiple lines, bottom-aligned (the default)
- * '%^' - render on multiple lines, top-aligned
- * '%,' - render on one line, comma-separated
+ || 2017/11/30 2017/12/31
+======================++=================================================
+ <unbudgeted> || $20 $120
+ assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960]
+ expenses:bus || $49 [98% of $50] $102 [102% of $100]
+ expenses:food || $396 [99% of $400] $808 [101% of $800]
+ expenses:movies || $30 [100% of $30] $30 [50% of $60]
+ income || $1950 [98% of $2000] $4050 [101% of $4000]
+----------------------++-------------------------------------------------
+ || 0 0
- 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.
+ Note, the '-S/--sort-amount' flag is not yet fully supported with
+'--budget'.
- Some example formats:
+ For more examples, see Budgeting and Forecasting.
- * '%(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
+4.4.8 Output format
+-------------------
- This command also supports output destination and output format
+The balance command supports output destination and output format
selection.

-File: hledger.info, Node: Colour support, Prev: Custom balance output, Up: balance
-
-4.4.6 Colour support
---------------------
-
-The balance command shows negative amounts in red, if:
-
- * the 'TERM' environment variable is not set to 'dumb'
- * the output is not being redirected or piped anywhere
-
-
File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: COMMANDS
4.5 balancesheet
@@ -2393,135 +2418,138 @@ hledger-check.hs checks more powerful account balance assertions.

Tag Table:
Node: Top68
-Node: EXAMPLES1882
-Ref: #examples1982
-Node: OPTIONS3628
-Ref: #options3730
-Node: General options4095
-Ref: #general-options4220
-Node: Command options6819
-Ref: #command-options6970
-Node: Command arguments7368
-Ref: #command-arguments7522
-Node: Argument files7643
-Ref: #argument-files7794
-Node: Special characters8060
-Ref: #special-characters8213
-Node: Input files9632
-Ref: #input-files9768
-Node: Smart dates11738
-Ref: #smart-dates11879
-Node: Report start & end date12858
-Ref: #report-start-end-date13028
-Node: Report intervals14093
-Ref: #report-intervals14256
-Node: Period expressions14657
-Ref: #period-expressions14817
-Node: Depth limiting18774
-Ref: #depth-limiting18918
-Node: Pivoting19260
-Ref: #pivoting19378
-Node: Cost21054
-Ref: #cost21162
-Node: Market value21280
-Ref: #market-value21415
-Node: Combining -B and -V22598
-Ref: #combining--b-and--v22761
-Node: Output destination22908
-Ref: #output-destination23070
-Node: Output format23353
-Ref: #output-format23505
-Node: Regular expressions23890
-Ref: #regular-expressions24027
-Node: QUERIES25388
-Ref: #queries25490
-Node: COMMANDS29457
-Ref: #commands29569
-Node: accounts30551
-Ref: #accounts30649
-Node: activity31895
-Ref: #activity32005
-Node: add32365
-Ref: #add32464
-Node: balance35125
-Ref: #balance35236
-Node: Flat mode38740
-Ref: #flat-mode38865
-Node: Depth limited balance reports39285
-Ref: #depth-limited-balance-reports39486
-Node: Multicolumn balance reports39906
-Ref: #multicolumn-balance-reports40101
-Node: Budgets44790
-Ref: #budgets44937
-Node: Custom balance output48906
-Ref: #custom-balance-output49068
-Node: Colour support51234
-Ref: #colour-support51366
-Node: balancesheet51539
-Ref: #balancesheet51675
-Node: balancesheetequity53986
-Ref: #balancesheetequity54135
-Node: cashflow54672
-Ref: #cashflow54800
-Node: check-dates56923
-Ref: #check-dates57050
-Node: check-dupes57167
-Ref: #check-dupes57291
-Node: close57428
-Ref: #close57535
-Node: help57865
-Ref: #help57965
-Node: import59039
-Ref: #import59153
-Node: incomestatement59883
-Ref: #incomestatement60017
-Node: prices62421
-Ref: #prices62536
-Node: print62579
-Ref: #print62689
-Node: print-unique67583
-Ref: #print-unique67709
-Node: register67777
-Ref: #register67904
-Node: Custom register output72405
-Ref: #custom-register-output72534
-Node: register-match73764
-Ref: #register-match73898
-Node: rewrite74081
-Ref: #rewrite74198
-Node: stats74267
-Ref: #stats74370
-Node: tags75240
-Ref: #tags75338
-Node: test75574
-Ref: #test75658
-Node: ADD-ON COMMANDS76026
-Ref: #add-on-commands76136
-Node: Official add-ons77423
-Ref: #official-add-ons77563
-Node: api77650
-Ref: #api77739
-Node: ui77791
-Ref: #ui77890
-Node: web77948
-Ref: #web78037
-Node: Third party add-ons78083
-Ref: #third-party-add-ons78258
-Node: diff78393
-Ref: #diff78490
-Node: iadd78589
-Ref: #iadd78703
-Node: interest78786
-Ref: #interest78907
-Node: irr79002
-Ref: #irr79100
-Node: Experimental add-ons79178
-Ref: #experimental-add-ons79330
-Node: autosync79610
-Ref: #autosync79721
-Node: chart79960
-Ref: #chart80079
-Node: check80150
-Ref: #check80252
+Node: EXAMPLES1886
+Ref: #examples1986
+Node: OPTIONS3632
+Ref: #options3734
+Node: General options4099
+Ref: #general-options4224
+Node: Command options6823
+Ref: #command-options6974
+Node: Command arguments7372
+Ref: #command-arguments7526
+Node: Argument files7647
+Ref: #argument-files7798
+Node: Special characters8064
+Ref: #special-characters8217
+Node: Input files9636
+Ref: #input-files9772
+Node: Smart dates11742
+Ref: #smart-dates11883
+Node: Report start & end date12862
+Ref: #report-start-end-date13032
+Node: Report intervals14097
+Ref: #report-intervals14260
+Node: Period expressions14661
+Ref: #period-expressions14821
+Node: Depth limiting18778
+Ref: #depth-limiting18922
+Node: Pivoting19264
+Ref: #pivoting19382
+Node: Cost21058
+Ref: #cost21166
+Node: Market value21284
+Ref: #market-value21419
+Node: Combining -B and -V22602
+Ref: #combining--b-and--v22765
+Node: Output destination22912
+Ref: #output-destination23074
+Node: Output format23357
+Ref: #output-format23509
+Node: Regular expressions23894
+Ref: #regular-expressions24031
+Node: QUERIES25392
+Ref: #queries25494
+Node: COMMANDS29456
+Ref: #commands29568
+Node: accounts30550
+Ref: #accounts30648
+Node: activity31894
+Ref: #activity32004
+Node: add32364
+Ref: #add32463
+Node: balance35124
+Ref: #balance35235
+Node: Classic balance report38318
+Ref: #classic-balance-report38491
+Node: Customising the classic balance report39860
+Ref: #customising-the-classic-balance-report40088
+Node: Colour support42162
+Ref: #colour-support42329
+Node: Flat mode42502
+Ref: #flat-mode42650
+Node: Depth limited balance reports43063
+Ref: #depth-limited-balance-reports43263
+Node: Multicolumn balance report43719
+Ref: #multicolumn-balance-report43917
+Node: Budget report49097
+Ref: #budget-report49240
+Ref: #output-format-152274
+Node: balancesheet52352
+Ref: #balancesheet52488
+Node: balancesheetequity54799
+Ref: #balancesheetequity54948
+Node: cashflow55485
+Ref: #cashflow55613
+Node: check-dates57736
+Ref: #check-dates57863
+Node: check-dupes57980
+Ref: #check-dupes58104
+Node: close58241
+Ref: #close58348
+Node: help58678
+Ref: #help58778
+Node: import59852
+Ref: #import59966
+Node: incomestatement60696
+Ref: #incomestatement60830
+Node: prices63234
+Ref: #prices63349
+Node: print63392
+Ref: #print63502
+Node: print-unique68396
+Ref: #print-unique68522
+Node: register68590
+Ref: #register68717
+Node: Custom register output73218
+Ref: #custom-register-output73347
+Node: register-match74577
+Ref: #register-match74711
+Node: rewrite74894
+Ref: #rewrite75011
+Node: stats75080
+Ref: #stats75183
+Node: tags76053
+Ref: #tags76151
+Node: test76387
+Ref: #test76471
+Node: ADD-ON COMMANDS76839
+Ref: #add-on-commands76949
+Node: Official add-ons78236
+Ref: #official-add-ons78376
+Node: api78463
+Ref: #api78552
+Node: ui78604
+Ref: #ui78703
+Node: web78761
+Ref: #web78850
+Node: Third party add-ons78896
+Ref: #third-party-add-ons79071
+Node: diff79206
+Ref: #diff79303
+Node: iadd79402
+Ref: #iadd79516
+Node: interest79599
+Ref: #interest79720
+Node: irr79815
+Ref: #irr79913
+Node: Experimental add-ons79991
+Ref: #experimental-add-ons80143
+Node: autosync80423
+Ref: #autosync80534
+Node: chart80773
+Ref: #chart80892
+Node: check80963
+Ref: #check81065

End Tag Table
diff --git a/embeddedfiles/hledger.txt b/embeddedfiles/hledger.txt
index eaa7c5a..c179ae3 100644
--- a/embeddedfiles/hledger.txt
+++ b/embeddedfiles/hledger.txt
@@ -728,11 +728,10 @@ QUERIES
The following kinds of search terms can be used. Remember these can
also be prefixed with not:, eg to exclude a particular subaccount.
- REGEX match account names by this regular expression. (No prefix is
- equivalent to acct:).
-
- acct:REGEX
- same as above
+ REGEX, acct:REGEX
+ match account names by this regular expression. (With no pre-
+ fix, acct: is assumed.)
+ same as above
amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N
match postings with a single-commodity amount that is equal to,
@@ -1028,8 +1027,31 @@ COMMANDS
--show-unbudgeted
with -budget, show unbudgeted accounts also
- The balance command displays accounts and balances. It is hledger's
- most featureful and versatile command.
+ The balance command is hledger's most versatile command. Note, despite
+ the name, it is not always used for showing real-world account bal-
+ ances; the more accounting-aware balancesheet and incomestatement may
+ be more convenient for that.
+
+ By default, it displays all accounts, and each account's change in bal-
+ ance during the entire period of the journal. Balance changes are cal-
+ culated by adding up the postings in each account. You can limit the
+ postings matched, by a query, to see fewer accounts, changes over a
+ different time period, changes from only cleared transactions, etc.
+
+ If you include an account's complete history of postings in the report,
+ the balance change is equivalent to the account's current ending bal-
+ ance. For a real-world account, typically you won't have all transac-
+ tions in the journal; instead you'll have all transactions after a cer-
+ tain date, and an "opening balances" transaction setting the correct
+ starting balance on that date. Then the balance command will show
+ real-world account balances. In some cases the -H/-historical flag is
+ used to ensure this (more below).
+
+ The balance command can produce several styles of report:
+
+ Classic balance report
+ This is the original balance report, as found in Ledger. It usually
+ looks like this:
$ hledger balance
$-1 assets
@@ -1045,62 +1067,135 @@ COMMANDS
--------------------
0
- More precisely, the balance command shows the change to each account's
- balance caused by all (matched) postings. In the common case where you
- do not filter by date and your journal sets the correct opening bal-
- ances, this is the same as the account's ending balance.
-
- By default, accounts are displayed hierarchically, with subaccounts
- indented below their parent. At each level of the tree, accounts are
- sorted by account code if any, then by account name. Or with
+ By default, accounts are displayed hierarchically, with subaccounts
+ indented below their parent. At each level of the tree, accounts are
+ sorted by account code if any, then by account name. Or with
-S/--sort-amount, by their balance amount.
"Boring" accounts, which contain a single interesting subaccount and no
- balance of their own, are elided into the following line for more com-
- pact output. (Not yet supported in tabular reports.) Use --no-elide to
+ balance of their own, are elided into the following line for more com-
+ pact output. (Eg above, the "liabilities" account.) Use --no-elide to
prevent this.
- Account balances are "inclusive" - they include the balances of any
+ Account balances are "inclusive" - they include the balances of any
subaccounts.
- Accounts which have zero balance (and no non-zero subaccounts) are
+ Accounts which have zero balance (and no non-zero subaccounts) are
omitted. Use -E/--empty to show them.
- A final total is displayed by default; use -N/--no-total to suppress
- it:
+ A final total is displayed by default; use -N/--no-total to suppress
+ it, eg:
$ hledger balance -p 2008/6 expenses --no-total
$2 expenses
$1 food
$1 supplies
+ Customising the classic balance report
+ You can customise the layout of classic balance reports with --for-
+ mat FMT:
+
+ $ hledger balance --format "%20(account) %12(total)"
+ assets $-1
+ bank:saving $1
+ cash $-2
+ expenses $2
+ food $1
+ supplies $1
+ income $-2
+ gifts $-1
+ salary $-1
+ liabilities:debts $1
+ ---------------------------------
+ 0
+
+ The FMT format string (plus a newline) specifies the formatting applied
+ to each account/balance pair. It may contain any suitable text, with
+ data fields interpolated like so:
+
+ %[MIN][.MAX](FIELDNAME)
+
+ 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
+ effect, 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
+
+ Colour support
+ The balance command shows negative amounts in red, if:
+
+ o the TERM environment variable is not set to dumb
+
+ o the output is not being redirected or piped anywhere
+
Flat mode
- To see a flat list of full account names instead of the default hierar-
- chical display, use --flat. In this mode, accounts (unless
- depth-clipped) show their "exclusive" balance, excluding any subaccount
- balances. In this mode, you can also use --drop N to omit the first
- few account name components.
+ To see a flat list instead of the default hierarchical display, use
+ --flat. In this mode, accounts (unless depth-clipped) show their full
+ names and "exclusive" balance, excluding any subaccount balances. In
+ this mode, you can also use --drop N to omit the first few account name
+ components.
$ hledger balance -p 2008/6 expenses -N --flat --drop 1
$1 food
$1 supplies
Depth limited balance reports
- With --depth N, balance shows accounts only to the specified depth.
- This is very useful to show a complex charts of accounts in less
- detail. In flat mode, balances from accounts below the depth limit
- will be shown as part of a parent account at the depth limit.
+ With --depth N or depth:N or just -N, balance reports show accounts
+ only to the specified numeric depth. This is very useful to summarise
+ a complex set of accounts and get an overview.
- $ hledger balance -N --depth 1
+ $ hledger balance -N -1
$-1 assets
$2 expenses
$-2 income
$1 liabilities
- Multicolumn balance reports
- With a reporting interval, multiple balance columns will be shown, one
- for each report period. There are three types of multi-column balance
- report, showing different information:
+ Flat-mode balance reports, which normally show exclusive balances, show
+ inclusive balances at the depth limit.
+
+ Multicolumn balance report
+ Multicolumn or tabular balance reports are a very useful hledger fea-
+ ture, and usually the preferred style. They share many of the above
+ features, but they show the report as a table, with columns represent-
+ ing time periods. This mode is activated by providing a reporting
+ interval.
+
+ There are three types of multicolumn balance report, showing different
+ information:
1. By default: each column shows the sum of postings in that period, ie
the account's change of balance in that period. This is useful eg
@@ -1152,7 +1247,7 @@ COMMANDS
----------------------++-------------------------------------
|| 0 0 0
- Multi-column balance reports display accounts in flat mode by default;
+ Multicolumn balance reports display accounts in flat mode by default;
to see the hierarchy, use --tree.
With a reporting interval (like --quarterly above), the report
@@ -1192,14 +1287,23 @@ COMMANDS
# Average is rounded to the dollar here since all journal amounts are
- Budgets
- With --budget and a report interval, all periodic transactions in your
- journal with that interval, active during the requested report period,
- are interpreted as recurring budget goals for the specified accounts
- (and subaccounts), and the report will show the difference between
- actual and budgeted balances.
+ Limitations:
+
+ In multicolumn reports the -V/--value flag uses the market price on the
+ report end date, for all columns (not the price on each column's end
+ date).
+
+ Eliding of boring parent accounts in tree mode, as in the classic bal-
+ ance report, is not yet supported in multicolumn reports.
- For example, you can take average monthly expenses in the common
+ Budget report
+ With --budget, extra columns are displayed showing budget goals for
+ each account and period, if any. Budget goals are defined by periodic
+ transactions. This is very useful for comparing planned and actual
+ income, expenses, time usage, etc. -budget is most often combined with
+ a report interval.
+
+ For example, you can take average monthly expenses in the common
expense categories to construct a minimal monthly budget:
;; Budget
@@ -1226,144 +1330,59 @@ COMMANDS
expenses:gifts $100
assets:bank:checking
- You can now see a monthly budget performance report:
+ You can now see a monthly budget report:
$ hledger balance -M --budget
- Balance changes in 2017/11/01-2017/12/31:
-
- || 2017/11 2017/12
- =======================++=================================================
- <unbudgeted>:expenses || $20 $100
- assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
- expenses:bus || $49 [98% of $50] $53 [106% of $50]
- expenses:food || $396 [99% of $400] $412 [103% of $400]
- expenses:movies || $30 [100% of $30] 0 [0% of $30]
- income || $1950 [98% of $2000] $2100 [105% of $2000]
- -----------------------++-------------------------------------------------
- || 0 0
-
- You can roll over unspent budgets to next period with --cumulative:
-
- $ hledger balance -M --budget --cumulative
- Ending balances (cumulative) in 2017/11/01-2017/12/31:
-
- || 2017/11/30 2017/12/31
- =======================++=================================================
- <unbudgeted>:expenses || $20 $120
- assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960]
- expenses:bus || $49 [98% of $50] $102 [102% of $100]
- expenses:food || $396 [99% of $400] $808 [101% of $800]
- expenses:movies || $30 [100% of $30] $30 [50% of $60]
- income || $1950 [98% of $2000] $4050 [101% of $4000]
- -----------------------++-------------------------------------------------
- || 0 0
-
- Accounts with no budget goals (not mentioned in the periodic transac-
- tions) will be aggregated under <unbudgeted>, unless you add the
- --show-unbudgeted flag to display them normally:
-
- $ hledger balance --budget --show-unbudgeted
- Balance changes in 2017/11/01-2017/12/31:
+ Budget performance in 2017/11/01-2017/12/31:
|| 2017/11 2017/12
======================++=================================================
+ <unbudgeted> || $20 $100
assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
expenses:bus || $49 [98% of $50] $53 [106% of $50]
expenses:food || $396 [99% of $400] $412 [103% of $400]
- expenses:gifts || 0 $100
expenses:movies || $30 [100% of $30] 0 [0% of $30]
- expenses:supplies || $20 0
income || $1950 [98% of $2000] $2100 [105% of $2000]
----------------------++-------------------------------------------------
|| 0 0
- Note -budget first arrived in hledger in 1.5 and is still pretty young;
- join the discussions on mail list and issue tracker to help us refine
- it.
-
- For more examples, see Budgeting and Forecasting.
-
- Custom balance output
- You can customise the layout of simple (non-tabular) balance reports
- with --format FMT:
+ By default, only accounts with budget goals during the report period
+ are shown. --show-unbudgeted shows unbudgeted accounts as well.
+ Top-level accounts with no budget goals anywhere below them are grouped
+ under <unbudgeted>.
- $ hledger balance --format "%20(account) %12(total)"
- assets $-1
- bank:saving $1
- cash $-2
- expenses $2
- food $1
- supplies $1
- income $-2
- gifts $-1
- salary $-1
- liabilities:debts $1
- ---------------------------------
- 0
-
- The FMT format string (plus a newline) specifies the formatting applied
- to each account/balance pair. It may contain any suitable text, with
- data fields interpolated like so:
-
- %[MIN][.MAX](FIELDNAME)
-
- 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
- effect, 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
+ You can roll over unspent budgets to next period with --cumulative:
- o %20(total) %2(depth_spacer)%-(account) - the default format for the
- single-column balance report
+ $ hledger balance -M --budget --cumulative
+ Budget performance in 2017/11/01-2017/12/31:
- This command also supports output destination and output format selec-
- tion.
+ || 2017/11/30 2017/12/31
+ ======================++=================================================
+ <unbudgeted> || $20 $120
+ assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960]
+ expenses:bus || $49 [98% of $50] $102 [102% of $100]
+ expenses:food || $396 [99% of $400] $808 [101% of $800]
+ expenses:movies || $30 [100% of $30] $30 [50% of $60]
+ income || $1950 [98% of $2000] $4050 [101% of $4000]
+ ----------------------++-------------------------------------------------
+ || 0 0
- Colour support
- The balance command shows negative amounts in red, if:
+ Note, the -S/--sort-amount flag is not yet fully supported with --bud-
+ get.
- o the TERM environment variable is not set to dumb
+ For more examples, see Budgeting and Forecasting.
- o the output is not being redirected or piped anywhere
+ Output format
+ The balance command supports output destination and output format
+ selection.
balancesheet
This command displays a simple balance sheet, showing historical ending
- balances of asset and liability accounts (ignoring any report begin
- date). It assumes that these accounts are under a top-level asset or
- liability account (case insensitive, plural forms also allowed). Note
- this report shows all account balances with normal positive sign (like
- conventional financial statements, unlike balance/print/register)
+ balances of asset and liability accounts (ignoring any report begin
+ date). It assumes that these accounts are under a top-level asset or
+ liability account (case insensitive, plural forms also allowed). Note
+ this report shows all account balances with normal positive sign (like
+ conventional financial statements, unlike balance/print/register)
(experimental). (bs)
--change
@@ -1371,7 +1390,7 @@ COMMANDS
balances
--cumulative
- show balance change accumulated across periods (in multicolumn
+ show balance change accumulated across periods (in multicolumn
reports), instead of historical ending balances
-H --historical
@@ -1427,16 +1446,16 @@ COMMANDS
0
With a reporting interval, multiple columns will be shown, one for each
- report period. As with multicolumn balance reports, you can alter the
- report mode with --change/--cumulative/--historical. Normally bal-
- ancesheet shows historical ending balances, which is what you need for
+ report period. As with multicolumn balance reports, you can alter the
+ report mode with --change/--cumulative/--historical. Normally bal-
+ ancesheet shows historical ending balances, which is what you need for
a balance sheet; note this means it ignores report begin dates.
- This command also supports output destination and output format selec-
+ This command also supports output destination and output format selec-
tion.
balancesheetequity
- Just like balancesheet, but also reports Equity (which it assumes is
+ Just like balancesheet, but also reports Equity (which it assumes is
under a top-level equity account).
Example:
@@ -1466,10 +1485,10 @@ COMMANDS
0
cashflow
- This command displays a simple cashflow statement, showing changes in
- "cash" accounts. It assumes that these accounts are under a top-level
- asset account (case insensitive, plural forms also allowed) and do not
- contain receivable or A/R in their name. Note this report shows all
+ This command displays a simple cashflow statement, showing changes in
+ "cash" accounts. It assumes that these accounts are under a top-level
+ asset account (case insensitive, plural forms also allowed) and do not
+ contain receivable or A/R in their name. Note this report shows all
account balances with normal positive sign (like conventional financial
statements, unlike balance/print/register) (experimental). (cf)
@@ -1477,7 +1496,7 @@ COMMANDS
show balance change in each period (default)
--cumulative
- show balance change accumulated across periods (in multicolumn
+ show balance change accumulated across periods (in multicolumn
reports), instead of changes during periods
-H --historical
@@ -1528,38 +1547,38 @@ COMMANDS
$-1
With a reporting interval, multiple columns will be shown, one for each
- report period. Normally cashflow shows changes in assets per period,
- though as with multicolumn balance reports you can alter the report
+ report period. Normally cashflow shows changes in assets per period,
+ though as with multicolumn balance reports you can alter the report
mode with --change/--cumulative/--historical.
- This command also supports output destination and output format selec-
+ This command also supports output destination and output format selec-
tion.
check-dates
- Check that transactions are sorted by increasing date. With a query,
+ Check that transactions are sorted by increasing date. With a query,
only matched transactions' dates are checked.
check-dupes
- Report account names having the same leaf but different prefixes. An
+ Report account names having the same leaf but different prefixes. An
example: http://stefanorodighiero.net/software/hledger-dupes.html
close
- Print closing/opening transactions that bring some or all account bal-
- ances to zero and back. Can be useful for bringing asset/liability
+ Print closing/opening transactions that bring some or all account bal-
+ ances to zero and back. Can be useful for bringing asset/liability
balances across file boundaries, or for closing out income/expenses for
- a period. This was formerly called "equity", as in Ledger, and that
+ a period. This was formerly called "equity", as in Ledger, and that
alias is also accepted. See close -help for more.
help
Show any of the hledger manuals.
- The help command displays any of the main hledger manuals, in one of
- several ways. Run it with no argument to list the manuals, or provide
+ The help command displays any of the main hledger manuals, in one of
+ several ways. Run it with no argument to list the manuals, or provide
a full or partial manual name to select one.
- hledger manuals are available in several formats. hledger help will
- use the first of these display methods that it finds: info, man,
- $PAGER, less, stdout (or when non-interactive, just stdout). You can
+ hledger manuals are available in several formats. hledger help will
+ use the first of these display methods that it finds: info, man,
+ $PAGER, less, stdout (or when non-interactive, just stdout). You can
force a particular viewer with the --info, --man, --pager, --cat flags.
$ hledger help
@@ -1583,7 +1602,7 @@ COMMANDS
...
import
- Read new transactions added to each FILE since last run, and add them
+ Read new transactions added to each FILE since last run, and add them
to the main journal file.
--dry-run
@@ -1593,28 +1612,28 @@ COMMANDS
each one. So eg to add new transactions from all CSV files to the main
journal, it's just: hledger import *.csv
- New transactions are detected in the same way as print -new: by assum-
+ New transactions are detected in the same way as print -new: by assum-
ing transactions are always added to the input files in increasing date
order, and by saving .latest.FILE state files.
- The -dry-run output is in journal format, so you can filter it, eg to
+ The -dry-run output is in journal format, so you can filter it, eg to
see only uncategorised transactions:
$ hledger import --dry ... | hledger -f- print unknown --ignore-assertions
incomestatement
- This command displays a simple income statement, showing revenues and
- expenses during a period. It assumes that these accounts are under a
- top-level revenue or income or expense account (case insensitive, plu-
- ral forms also allowed). Note this report shows all account balances
- with normal positive sign (like conventional financial statements,
+ This command displays a simple income statement, showing revenues and
+ expenses during a period. It assumes that these accounts are under a
+ top-level revenue or income or expense account (case insensitive, plu-
+ ral forms also allowed). Note this report shows all account balances
+ with normal positive sign (like conventional financial statements,
unlike balance/print/register) (experimental). (is)
--change
show balance change in each period (default)
--cumulative
- show balance change accumulated across periods (in multicolumn
+ show balance change accumulated across periods (in multicolumn
reports), instead of changes during periods
-H --historical
@@ -1648,8 +1667,8 @@ COMMANDS
--sort-amount
sort by amount instead of account code/name
- This command displays a simple income statement. It currently assumes
- that you have top-level accounts named income (or revenue) and expense
+ This command displays a simple income statement. It currently assumes
+ that you have top-level accounts named income (or revenue) and expense
(plural forms also allowed.)
$ hledger incomestatement
@@ -1674,11 +1693,11 @@ COMMANDS
0
With a reporting interval, multiple columns will be shown, one for each
- report period. Normally incomestatement shows revenues/expenses per
- period, though as with multicolumn balance reports you can alter the
+ report period. Normally incomestatement shows revenues/expenses per
+ period, though as with multicolumn balance reports you can alter the
report mode with --change/--cumulative/--historical.
- This command also supports output destination and output format selec-
+ This command also supports output destination and output format selec-
tion.
prices
@@ -1688,7 +1707,7 @@ COMMANDS
Show transactions from the journal. Aliases: p, txns.
-m STR --match=STR
- show the transaction whose description is most similar to STR,
+ show the transaction whose description is most similar to STR,
and is most recent
--new show only newer-dated transactions added in each file since last
@@ -1701,7 +1720,7 @@ COMMANDS
select the output format. Supported formats: txt, csv.
-o FILE --output-file=FILE
- write output to FILE. A file extension matching one of the
+ write output to FILE. A file extension matching one of the
above formats selects that format.
$ hledger print
@@ -1732,39 +1751,39 @@ COMMANDS
it does not preserve directives or inter-transaction comments
Normally, the journal entry's explicit or implicit amount style is pre-
- served. Ie when an amount is omitted in the journal, it will be omit-
- ted in the output. You can use the -x/--explicit flag to make all
+ served. Ie when an amount is omitted in the journal, it will be omit-
+ ted in the output. You can use the -x/--explicit flag to make all
amounts explicit, which can be useful for troubleshooting or for making
your journal more readable and robust against data entry errors. Note,
- -x will cause postings with a multi-commodity amount (these can arise
- when a multi-commodity transaction has an implicit amount) will be
- split into multiple single-commodity postings, for valid journal out-
+ -x will cause postings with a multi-commodity amount (these can arise
+ when a multi-commodity transaction has an implicit amount) will be
+ split into multiple single-commodity postings, for valid journal out-
put.
- With -B/--cost, amounts with transaction prices are converted to cost
+ With -B/--cost, amounts with transaction prices are converted to cost
using that price. This can be used for troubleshooting.
- With -m/--match and a STR argument, print will show at most one trans-
- action: the one one whose description is most similar to STR, and is
- most recent. STR should contain at least two characters. If there is
+ With -m/--match and a STR argument, print will show at most one trans-
+ action: the one one whose description is most similar to STR, and is
+ most recent. STR should contain at least two characters. If there is
no similar-enough match, no transaction will be shown.
With --new, for each FILE being read, hledger reads (and writes) a spe-
- cial state file (.latest.FILE in the same directory), containing the
- latest transaction date(s) that were seen last time FILE was read.
- When this file is found, only transactions with newer dates (and new
- transactions on the latest date) are printed. This is useful for
- ignoring already-seen entries in import data, such as downloaded CSV
+ cial state file (.latest.FILE in the same directory), containing the
+ latest transaction date(s) that were seen last time FILE was read.
+ When this file is found, only transactions with newer dates (and new
+ transactions on the latest date) are printed. This is useful for
+ ignoring already-seen entries in import data, such as downloaded CSV
files. Eg:
$ hledger -f bank1.csv print --new
# shows transactions added since last print --new on this file
- This assumes that transactions added to FILE always have same or
- increasing dates, and that transactions on the same day do not get
+ This assumes that transactions added to FILE always have same or
+ increasing dates, and that transactions on the same day do not get
reordered. See also the import command.
- This command also supports output destination and output format selec-
+ This command also supports output destination and output format selec-
tion. Here's an example of print's CSV output:
$ hledger print -Ocsv
@@ -1781,20 +1800,20 @@ COMMANDS
"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
+ 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
+ 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"
+ 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
+ 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.)
print-unique
@@ -1807,7 +1826,7 @@ COMMANDS
show running total from report start date (default)
-H --historical
- show historical running total/balance (includes postings before
+ show historical running total/balance (includes postings before
report start date)
-A --average
@@ -1818,18 +1837,18 @@ COMMANDS
show postings' siblings instead
-w N --width=N
- set output width (default: terminal width or COLUMNS. -wN,M
+ set output width (default: terminal width or COLUMNS. -wN,M
sets description width as well)
-O FMT --output-format=FMT
select the output format. Supported formats: txt, csv.
-o FILE --output-file=FILE
- write output to FILE. A file extension matching one of the
+ write output to FILE. A file extension matching one of the
above formats selects that format.
The register command displays postings, one per line, and their running
- total. This is typically used with a query selecting a particular
+ total. This is typically used with a query selecting a particular
account, to see that account's activity:
$ hledger register checking
@@ -1838,8 +1857,8 @@ COMMANDS
2008/06/02 save assets:bank:checking $-1 $1
2008/12/31 pay off assets:bank:checking $-1 0
- The --historical/-H flag adds the balance from any undisplayed prior
- postings to the running total. This is useful when you want to see
+ 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
@@ -1849,23 +1868,23 @@ COMMANDS
The --depth option limits the amount of sub-account detail displayed.
- The --average/-A flag shows the running average posting amount instead
+ 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
+ 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 --related/-r flag shows the other postings in the transactions of
the postings which would normally be shown.
- With a reporting interval, register shows summary postings, one per
+ 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
+ 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
@@ -1882,7 +1901,7 @@ COMMANDS
2008/11 0 $-2
2008/12 0 $-2
- Often, you'll want to see just one line per interval. The --depth
+ Often, you'll want to see just one line per interval. The --depth
option helps with this, causing subaccounts to be aggregated:
$ hledger register --monthly assets --depth 1h
@@ -1890,18 +1909,18 @@ COMMANDS
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
+ 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.
Custom register output
- register uses the full terminal width by default, except on windows.
- You can override this by setting the COLUMNS environment variable (not
+ register uses the full terminal width by default, except on windows.
+ You can override this by setting the COLUMNS environment variable (not
a bash shell variable) or by using the --width/-w option.
- The description and account columns normally share the space equally
- (about half of (width - 40) each). You can adjust this by adding a
+ 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:
@@ -1918,12 +1937,12 @@ COMMANDS
$ hledger reg -w 100,40 # set overall width 100, description width 40
$ hledger reg -w $COLUMNS,40 # use terminal width, and set description width
- This command also supports output destination and output format selec-
+ This command also supports output destination and output format selec-
tion.
register-match
Print the one posting whose transaction description is closest to DESC,
- in the style of the register command. Helps ledger-autosync detect
+ in the style of the register command. Helps ledger-autosync detect
already-seen transactions when importing.
rewrite
@@ -1933,7 +1952,7 @@ COMMANDS
Show some journal statistics.
-o FILE --output-file=FILE
- write output to FILE. A file extension matching one of the
+ write output to FILE. A file extension matching one of the
above formats selects that format.
$ hledger stats
@@ -1948,16 +1967,16 @@ COMMANDS
Accounts : 8 (depth 3)
Commodities : 1 ($)
- The stats command displays summary information for the whole journal,
- or a matched part of it. With a reporting interval, it shows a report
+ The stats command displays summary information for the whole journal,
+ or a matched part of it. With a reporting interval, it shows a report
for each report period.
- This command also supports output destination and output format selec-
+ This command also supports output destination and output format selec-
tion.
tags
- List all the tag names used in the journal. With a TAGREGEX argument,
- only tag names matching the regular expression (case insensitive) are
+ List all the tag names used in the journal. With a TAGREGEX argument,
+ only tag names matching the regular expression (case insensitive) are
shown. With additional QUERY arguments, only transactions matching the
query are considered.
@@ -1967,34 +1986,34 @@ COMMANDS
$ hledger test
Cases: 74 Tried: 74 Errors: 0 Failures: 0
- This command runs hledger's built-in unit tests and displays a quick
+ This command runs hledger's built-in unit tests and displays a quick
report. With a regular expression argument, it selects only tests with
matching names. It's mainly used in development, but it's also nice to
be able to check your hledger executable for smoke at any time.
ADD-ON COMMANDS
- hledger also searches for external add-on commands, and will include
+ hledger also searches for external add-on commands, and will include
these in the commands list. These are programs or scripts in your PATH
- whose name starts with hledger- and ends with a recognised file exten-
+ whose name starts with hledger- and ends with a recognised file exten-
sion (currently: no extension, bat,com,exe, hs,lhs,pl,py,rb,rkt,sh).
- Add-ons can be invoked like any hledger command, but there are a few
+ Add-ons can be invoked like any hledger command, but there are a few
things to be aware of. Eg if the hledger-web add-on is installed,
o hledger -h web shows hledger's help, while hledger web -h shows
hledger-web's help.
- o Flags specific to the add-on must have a preceding -- to hide them
- from hledger. So hledger web --serve --port 9000 will be rejected;
+ o Flags specific to the add-on must have a preceding -- to hide them
+ from hledger. So hledger web --serve --port 9000 will be rejected;
you must use hledger web -- --serve --port 9000.
- o You can always run add-ons directly if preferred:
+ o You can always run add-ons directly if preferred:
hledger-web --serve --port 9000.
- Add-ons are a relatively easy way to add local features or experiment
- with new ideas. They can be written in any language, but haskell
- scripts have a big advantage: they can use the same hledger (and
- haskell) library functions that built-in commands do, for command-line
+ Add-ons are a relatively easy way to add local features or experiment
+ with new ideas. They can be written in any language, but haskell
+ scripts have a big advantage: they can use the same hledger (and
+ haskell) library functions that built-in commands do, for command-line
options, journal parsing, reporting, etc.
Here are some hledger add-ons available:
@@ -2012,7 +2031,7 @@ ADD-ON COMMANDS
hledger-web provides a simple web interface.
Third party add-ons
- These are maintained separately, and usually updated shortly after a
+ These are maintained separately, and usually updated shortly after a
hledger release.
diff
@@ -2020,7 +2039,7 @@ ADD-ON COMMANDS
journal file and another.
iadd
- hledger-iadd is a curses-style, more interactive replacement for the
+ hledger-iadd is a curses-style, more interactive replacement for the
add command.
interest
@@ -2028,19 +2047,19 @@ ADD-ON COMMANDS
ing to various schemes.
irr
- hledger-irr calculates the internal rate of return of an investment
+ hledger-irr calculates the internal rate of return of an investment
account.
Experimental add-ons
- These are available in source form in the hledger repo's bin/ direc-
+ These are available in source form in the hledger repo's bin/ direc-
tory; installing them is pretty easy. They may be less mature and doc-
- umented than built-in commands. Reading and tweaking these is a good
+ umented than built-in commands. Reading and tweaking these is a good
way to start making your own!
autosync
hledger-autosync is a symbolic link for easily running ledger-autosync,
- if installed. ledger-autosync does deduplicating conversion of OFX
- data and some CSV formats, and can also download the data if your bank
+ if installed. ledger-autosync does deduplicating conversion of OFX
+ data and some CSV formats, and can also download the data if your bank
offers OFX Direct Connect.
chart
@@ -2050,21 +2069,21 @@ ADD-ON COMMANDS
hledger-check.hs checks more powerful account balance assertions.
ENVIRONMENT
- COLUMNS The screen width used by the register command. Default: the
+ COLUMNS The screen width used by the register command. Default: the
full terminal width.
LEDGER_FILE The journal file path when not specified with -f. Default:
- ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
+ ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
nal).
FILES
- Reads data from one or more files in hledger journal, timeclock, time-
- dot, or CSV format specified with -f, or $LEDGER_FILE, or
- $HOME/.hledger.journal (on windows, perhaps
+ Reads data from one or more files in hledger journal, timeclock, time-
+ dot, or CSV format specified with -f, or $LEDGER_FILE, or
+ $HOME/.hledger.journal (on windows, perhaps
C:/Users/USER/.hledger.journal).
BUGS
- The need to precede addon command options with -- when invoked from
+ The need to precede addon command options with -- when invoked from
hledger is awkward.
When input data contains non-ascii characters, a suitable system locale
@@ -2077,33 +2096,33 @@ BUGS
In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger
add.
- Not all of Ledger's journal file syntax is supported. See file format
+ Not all of Ledger's journal file syntax is supported. See file format
differences.
- On large data files, hledger is slower and uses more memory than
+ On large data files, hledger is slower and uses more memory than
Ledger.
TROUBLESHOOTING
- Here are some issues you might encounter when you run hledger (and
- remember you can also seek help from the IRC channel, mail list or bug
+ Here are some issues you might encounter when you run hledger (and
+ remember you can also seek help from the IRC channel, mail list or bug
tracker):
Successfully installed, but "No command `hledger' found"
stack and cabal install binaries into a special directory, which should
- be added to your PATH environment variable. Eg on unix-like systems,
+ be added to your PATH environment variable. Eg on unix-like systems,
that is ~/.local/bin and ~/.cabal/bin respectively.
I set a custom LEDGER_FILE, but hledger is still using the default file
- LEDGER_FILE should be a real environment variable, not just a shell
- variable. The command env | grep LEDGER_FILE should show it. You may
+ LEDGER_FILE should be a real environment variable, not just a shell
+ variable. The command env | grep LEDGER_FILE should show it. You may
need to use export. Here's an explanation.
- "Illegal byte sequence" or "Invalid or incomplete multibyte or wide
+ "Illegal byte sequence" or "Invalid or incomplete multibyte or wide
character" errors
In order to handle non-ascii letters and symbols (like ), hledger needs
an appropriate locale. This is usually configured system-wide; you can
also configure it temporarily. The locale may need to be one that sup-
- ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always,
+ ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always,
I'm not sure yet).
Here's an example of setting the locale temporarily, on ubuntu
@@ -2122,7 +2141,7 @@ TROUBLESHOOTING
$ echo "export LANG=en_US.UTF-8" >>~/.bash_profile
$ bash --login
- If we preferred to use eg fr_FR.utf8, we might have to install that
+ If we preferred to use eg fr_FR.utf8, we might have to install that
first:
$ apt-get install language-pack-fr
@@ -2143,7 +2162,7 @@ TROUBLESHOOTING
REPORTING BUGS
- Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
+ Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list)
@@ -2157,7 +2176,7 @@ COPYRIGHT
SEE ALSO
- hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
+ hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)
@@ -2165,4 +2184,4 @@ SEE ALSO
-hledger 1.9 March 2018 hledger(1)
+hledger 1.9.1 April 2018 hledger(1)
diff --git a/embeddedfiles/hledger_csv.5 b/embeddedfiles/hledger_csv.5
index 0ca4805..1043528 100644
--- a/embeddedfiles/hledger_csv.5
+++ b/embeddedfiles/hledger_csv.5
@@ -1,5 +1,5 @@
-.TH "hledger_csv" "5" "March 2018" "hledger 1.9" "hledger User Manuals"
+.TH "hledger_csv" "5" "April 2018" "hledger 1.9.1" "hledger User Manuals"
diff --git a/embeddedfiles/hledger_csv.info b/embeddedfiles/hledger_csv.info
index 5babf2e..0cf93c9 100644
--- a/embeddedfiles/hledger_csv.info
+++ b/embeddedfiles/hledger_csv.info
@@ -3,8 +3,8 @@ This is hledger_csv.info, produced by makeinfo version 6.5 from stdin.

File: hledger_csv.info, Node: Top, Next: CSV RULES, Up: (dir)
-hledger_csv(5) hledger 1.9
-**************************
+hledger_csv(5) hledger 1.9.1
+****************************
hledger can read CSV (comma-separated value) files as if they were
journal files, automatically converting each CSV record into a
@@ -317,33 +317,33 @@ one rules file will be used for all the CSV files being read.

Tag Table:
Node: Top72
-Node: CSV RULES2161
-Ref: #csv-rules2269
-Node: skip2531
-Ref: #skip2625
-Node: date-format2797
-Ref: #date-format2924
-Node: field list3430
-Ref: #field-list3567
-Node: field assignment4272
-Ref: #field-assignment4427
-Node: conditional block4931
-Ref: #conditional-block5085
-Node: include5981
-Ref: #include6111
-Node: newest-first6342
-Ref: #newest-first6456
-Node: CSV TIPS6867
-Ref: #csv-tips6961
-Node: CSV ordering7079
-Ref: #csv-ordering7197
-Node: CSV accounts7378
-Ref: #csv-accounts7516
-Node: CSV amounts7770
-Ref: #csv-amounts7916
-Node: CSV balance assertions8691
-Ref: #csv-balance-assertions8873
-Node: Reading multiple CSV files9078
-Ref: #reading-multiple-csv-files9248
+Node: CSV RULES2165
+Ref: #csv-rules2273
+Node: skip2535
+Ref: #skip2629
+Node: date-format2801
+Ref: #date-format2928
+Node: field list3434
+Ref: #field-list3571
+Node: field assignment4276
+Ref: #field-assignment4431
+Node: conditional block4935
+Ref: #conditional-block5089
+Node: include5985
+Ref: #include6115
+Node: newest-first6346
+Ref: #newest-first6460
+Node: CSV TIPS6871
+Ref: #csv-tips6965
+Node: CSV ordering7083
+Ref: #csv-ordering7201
+Node: CSV accounts7382
+Ref: #csv-accounts7520
+Node: CSV amounts7774
+Ref: #csv-amounts7920
+Node: CSV balance assertions8695
+Ref: #csv-balance-assertions8877
+Node: Reading multiple CSV files9082
+Ref: #reading-multiple-csv-files9252

End Tag Table
diff --git a/embeddedfiles/hledger_csv.txt b/embeddedfiles/hledger_csv.txt
index bd95bdd..b629029 100644
--- a/embeddedfiles/hledger_csv.txt
+++ b/embeddedfiles/hledger_csv.txt
@@ -249,4 +249,4 @@ SEE ALSO
-hledger 1.9 March 2018 hledger_csv(5)
+hledger 1.9.1 April 2018 hledger_csv(5)
diff --git a/embeddedfiles/hledger_journal.5 b/embeddedfiles/hledger_journal.5
index 0c3f102..2afe30b 100644
--- a/embeddedfiles/hledger_journal.5
+++ b/embeddedfiles/hledger_journal.5
@@ -1,6 +1,6 @@
.\"t
-.TH "hledger_journal" "5" "March 2018" "hledger 1.9" "hledger User Manuals"
+.TH "hledger_journal" "5" "April 2018" "hledger 1.9.1" "hledger User Manuals"
@@ -758,11 +758,6 @@ Lines in the journal beginning with a semicolon (\f[C];\f[]) or hash
(Star comments cause org\-mode nodes to be ignored, allowing emacs users
to fold and navigate their journals with org\-mode or orgstruct\-mode.)
.PP
-Also, anything between \f[C]comment\f[] and \f[C]end\ comment\f[]
-directives is a (multi\-line) comment.
-If there is no \f[C]end\ comment\f[], the comment extends to the end of
-the file.
-.PP
You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the
postings).
@@ -795,6 +790,9 @@ end\ comment
;\ a\ file\ comment\ (because\ not\ indented)
\f[]
.fi
+.PP
+You can also comment larger regions of a file using \f[C]comment\f[] and
+\f[C]end\ comment\f[] directives.
.SS Tags
.PP
Tags are a way to add extra labels or labelled data to postings and
@@ -855,7 +853,173 @@ For example, the following transaction has three tags (\f[C]A\f[],
Tags are like Ledger's metadata feature, except hledger's tag values are
simple strings.
.SS Directives
-.SS Account aliases
+.SS Comment blocks
+.PP
+A line containing just \f[C]comment\f[] starts a commented region of the
+file, and a line containing just \f[C]end\ comment\f[] (or the end of
+the current file) ends it.
+See also comments.
+.SS Including other files
+.PP
+You can pull in the content of additional files by writing an include
+directive, like this:
+.IP
+.nf
+\f[C]
+include\ path/to/file.journal
+\f[]
+.fi
+.PP
+If the path does not begin with a slash, it is relative to the current
+file.
+Glob patterns (\f[C]*\f[]) are not currently supported.
+.PP
+The \f[C]include\f[] directive can only be used in journal files.
+It can include journal, timeclock or timedot files, but not CSV files.
+.SS Default year
+.PP
+You can set a default year to be used for subsequent dates which don't
+specify a year.
+This is a line beginning with \f[C]Y\f[] followed by the year.
+Eg:
+.IP
+.nf
+\f[C]
+Y2009\ \ \ \ \ \ ;\ set\ default\ year\ to\ 2009
+
+12/15\ \ \ \ \ \ ;\ equivalent\ to\ 2009/12/15
+\ \ expenses\ \ 1
+\ \ assets
+
+Y2010\ \ \ \ \ \ ;\ change\ default\ year\ to\ 2010
+
+2009/1/30\ \ ;\ specifies\ the\ year,\ not\ affected
+\ \ expenses\ \ 1
+\ \ assets
+
+1/31\ \ \ \ \ \ \ ;\ equivalent\ to\ 2010/1/31
+\ \ expenses\ \ 1
+\ \ assets
+\f[]
+.fi
+.SS Declaring commodities
+.PP
+The \f[C]commodity\f[] directive declares commodities which may be used
+in the journal (though currently we do not enforce this).
+It may be written on a single line, like this:
+.IP
+.nf
+\f[C]
+;\ commodity\ EXAMPLEAMOUNT
+
+;\ display\ AAAA\ amounts\ with\ the\ symbol\ on\ the\ right,\ space\-separated,
+;\ using\ period\ as\ decimal\ point,\ with\ four\ decimal\ places,\ and
+;\ separating\ thousands\ with\ comma.
+commodity\ 1,000.0000\ AAAA
+\f[]
+.fi
+.PP
+or on multiple lines, using the \[lq]format\[rq] subdirective.
+In this case the commodity symbol appears twice and should be the same
+in both places:
+.IP
+.nf
+\f[C]
+;\ commodity\ SYMBOL
+;\ \ \ format\ EXAMPLEAMOUNT
+
+;\ 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\ 9,99,99,999.00
+\f[]
+.fi
+.PP
+Commodity directives have a second purpose: they define the standard
+display format for amounts in the commodity.
+Normally the display format is inferred from journal entries, but this
+can be unpredictable; declaring it with a commodity directive overrides
+this and removes ambiguity.
+Towards this end, amounts in commodity directives must always be written
+with a decimal point (a period or comma, followed by 0 or more decimal
+digits).
+.SS Default commodity
+.PP
+The D directive sets a default commodity (and display format), to be
+used for amounts without a commodity symbol (ie, plain numbers).
+(Note this differs from Ledger's default commodity directive.) The
+commodity and display format will be applied to all subsequent
+commodity\-less amounts, or until the next D directive.
+.IP
+.nf
+\f[C]
+#\ commodity\-less\ amounts\ should\ be\ treated\ as\ dollars
+#\ (and\ displayed\ with\ symbol\ on\ the\ left,\ thousands\ separators\ and\ two\ decimal\ places)
+D\ $1,000.00
+
+1/1
+\ \ a\ \ \ \ \ 5\ \ \ \ ;\ <\-\ commodity\-less\ amount,\ becomes\ $1
+\ \ b
+\f[]
+.fi
+.PP
+As with the \f[C]commodity\f[] directive, the amount must always be
+written with a decimal point.
+.SS Declaring accounts
+.PP
+The \f[C]account\f[] directive predeclares account names.
+The simplest form is \f[C]account\ ACCTNAME\f[], eg:
+.IP
+.nf
+\f[C]
+account\ assets:bank:checking
+\f[]
+.fi
+.PP
+Currently this mainly helps with account name autocompletion in eg
+hledger add, hledger\-iadd, hledger\-web, and ledger\-mode.
+.PD 0
+.P
+.PD
+In future it will also help detect misspelled accounts.
+.PP
+Account names can be followed by a numeric account code:
+.IP
+.nf
+\f[C]
+account\ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 1000
+account\ assets:bank:checking\ \ \ \ 1110
+account\ liabilities\ \ \ \ \ \ \ \ \ \ \ \ \ 2000
+account\ revenues\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4000
+account\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 6000
+\f[]
+.fi
+.PP
+This affects account display order in reports: accounts with codes are
+listed before accounts without codes, in increasing code order.
+(Otherwise, accounts are listed alphabetically.) Account codes should be
+all numeric digits, unique, and separated from the account name by at
+least two spaces (since account names may contain single spaces).
+By convention, often the first digit indicates the type of account, as
+in this numbering scheme and the example above.
+In future, we might use this to recognize account types.
+.PP
+An account directive can also have indented subdirectives following it,
+which are currently ignored.
+Here is the full syntax:
+.IP
+.nf
+\f[C]
+;\ account\ ACCTNAME\ \ [OPTIONALCODE]
+;\ \ \ [OPTIONALSUBDIRECTIVES]
+
+account\ assets:bank:checking\ \ \ 1110
+\ \ a\ comment
+\ \ some\-tag:12345
+\f[]
+.fi
+.SS Rewriting accounts
.PP
You can define aliases which rewrite your account names (after reading
the journal, before generating reports).
@@ -871,7 +1035,7 @@ combining two accounts into one
.IP \[bu] 2
customising reports
.PP
-See also Cookbook: rewrite account names.
+See also Cookbook: Rewrite account names.
.SS Basic aliases
.PP
To set an account alias, use the \f[C]alias\f[] directive in your
@@ -946,7 +1110,7 @@ alias directives, most recently seen first (recent directives take
precedence over earlier ones; directives not yet seen are ignored)
.IP "2." 3
alias options, in the order they appear on the command line
-.SS end aliases
+.SS \f[C]end\ aliases\f[]
.PP
You can clear (forget) all currently defined aliases with the
\f[C]end\ aliases\f[] directive:
@@ -956,60 +1120,7 @@ You can clear (forget) all currently defined aliases with the
end\ aliases
\f[]
.fi
-.SS account directive
-.PP
-The \f[C]account\f[] directive predeclares account names.
-The simplest form is \f[C]account\ ACCTNAME\f[], eg:
-.IP
-.nf
-\f[C]
-account\ assets:bank:checking
-\f[]
-.fi
-.PP
-Currently this mainly helps with account name autocompletion in eg
-hledger add, hledger\-iadd, hledger\-web, and ledger\-mode.
-.PD 0
-.P
-.PD
-In future it will also help detect misspelled accounts.
-.PP
-Account names can be followed by a numeric account code:
-.IP
-.nf
-\f[C]
-account\ assets\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 1000
-account\ assets:bank:checking\ \ \ \ 1110
-account\ liabilities\ \ \ \ \ \ \ \ \ \ \ \ \ 2000
-account\ revenues\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4000
-account\ expenses\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 6000
-\f[]
-.fi
-.PP
-This affects account display order in reports: accounts with codes are
-listed before accounts without codes, in increasing code order.
-(Otherwise, accounts are listed alphabetically.) Account codes should be
-all numeric digits, unique, and separated from the account name by at
-least two spaces (since account names may contain single spaces).
-By convention, often the first digit indicates the type of account, as
-in this numbering scheme and the example above.
-In future, we might use this to recognize account types.
-.PP
-An account directive can also have indented subdirectives following it,
-which are currently ignored.
-Here is the full syntax:
-.IP
-.nf
-\f[C]
-;\ account\ ACCTNAME\ \ [OPTIONALCODE]
-;\ \ \ [OPTIONALSUBDIRECTIVES]
-
-account\ assets:bank:checking\ \ \ 1110
-\ \ a\ comment
-\ \ some\-tag:12345
-\f[]
-.fi
-.SS apply account directive
+.SS Default parent account
.PP
You can specify a parent account which will be prepended to all accounts
within a section of the journal.
@@ -1054,116 +1165,13 @@ include\ personal.journal
.PP
Prior to hledger 1.0, legacy \f[C]account\f[] and \f[C]end\f[] spellings
were also supported.
-.SS Multi\-line comments
-.PP
-A line containing just \f[C]comment\f[] starts a multi\-line comment,
-and a line containing just \f[C]end\ comment\f[] ends it.
-See comments.
-.SS commodity directive
+.SS Periodic transactions
.PP
-The \f[C]commodity\f[] directive predefines commodities (currently this
-is just informational), and also it may define the display format for
-amounts in this commodity (overriding the automatically inferred
-format).
-.PP
-It may be written on a single line, like this:
-.IP
-.nf
-\f[C]
-;\ commodity\ EXAMPLEAMOUNT
-
-;\ display\ AAAA\ amounts\ with\ the\ symbol\ on\ the\ right,\ space\-separated,
-;\ using\ period\ as\ decimal\ point,\ with\ four\ decimal\ places,\ and
-;\ separating\ thousands\ with\ comma.
-commodity\ 1,000.0000\ AAAA
-\f[]
-.fi
-.PP
-or on multiple lines, using the \[lq]format\[rq] subdirective.
-In this case the commodity symbol appears twice and should be the same
-in both places:
-.IP
-.nf
-\f[C]
-;\ commodity\ SYMBOL
-;\ \ \ format\ EXAMPLEAMOUNT
-
-;\ 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\ 9,99,99,999.00
-\f[]
-.fi
-.SS Default commodity
-.PP
-The D directive sets a default commodity (and display format), to be
-used for amounts without a commodity symbol (ie, plain numbers).
-(Note this differs from Ledger's default commodity directive.) The
-commodity and display format will be applied to all subsequent
-commodity\-less amounts, or until the next D directive.
-.IP
-.nf
-\f[C]
-#\ commodity\-less\ amounts\ should\ be\ treated\ as\ dollars
-#\ (and\ displayed\ with\ symbol\ on\ the\ left,\ thousands\ separators\ and\ two\ decimal\ places)
-D\ $1,000.00
-
-1/1
-\ \ a\ \ \ \ \ 5\ \ \ \ ;\ <\-\ commodity\-less\ amount,\ becomes\ $1
-\ \ b
-\f[]
-.fi
-.SS Default year
-.PP
-You can set a default year to be used for subsequent dates which don't
-specify a year.
-This is a line beginning with \f[C]Y\f[] followed by the year.
-Eg:
-.IP
-.nf
-\f[C]
-Y2009\ \ \ \ \ \ ;\ set\ default\ year\ to\ 2009
-
-12/15\ \ \ \ \ \ ;\ equivalent\ to\ 2009/12/15
-\ \ expenses\ \ 1
-\ \ assets
-
-Y2010\ \ \ \ \ \ ;\ change\ default\ year\ to\ 2010
-
-2009/1/30\ \ ;\ specifies\ the\ year,\ not\ affected
-\ \ expenses\ \ 1
-\ \ assets
-
-1/31\ \ \ \ \ \ \ ;\ equivalent\ to\ 2010/1/31
-\ \ expenses\ \ 1
-\ \ assets
-\f[]
-.fi
-.SS Including other files
-.PP
-You can pull in the content of additional journal files by writing an
-include directive, like this:
-.IP
-.nf
-\f[C]
-include\ path/to/file.journal
-\f[]
-.fi
-.PP
-If the path does not begin with a slash, it is relative to the current
-file.
-Glob patterns (\f[C]*\f[]) are not currently supported.
-.PP
-The \f[C]include\f[] directive can only be used in journal files.
-It can include journal, timeclock or timedot files, but not CSV files.
-.SH Periodic transactions
-.PP
-Periodic transactions are a kind of rule with a dual purpose: they can
-specify recurring future transactions (with \f[C]\-\-forecast\f[]), or
-budget goals (with \f[C]\-\-budget\f[]).
-They look a bit like a transaction, except the first line is a tilde
-(\f[C]~\f[]) followed by a period expression:
+Periodic transaction rules (enabled by \f[C]\-\-forecast\f[] or
+\f[C]\-\-budget\f[]) describe recurring transactions.
+They look like a transaction where the first line is a tilde
+(\f[C]~\f[]) followed by a period expression (mnemonic: \f[C]~\f[] is
+like a recurring sine wave):
.IP
.nf
\f[C]
@@ -1173,25 +1181,34 @@ They look a bit like a transaction, except the first line is a tilde
\f[]
.fi
.PP
+Periodic transactions have a dual purpose:
+.IP \[bu] 2
With \f[C]\-\-forecast\f[], each periodic transaction rule generates
-recurring \[lq]forecast\[rq] transactions at the specified interval,
-beginning the day after the latest recorded journal transaction (or
-today, if there are no transactions) and ending 6 months from today (or
-at the report end date, if specified).
-.PP
-With \f[C]balance\ \-\-budget\f[], each periodic transaction declares
-recurring budget goals for the specified accounts.
+future transactions, recurring at the specified interval, which can be
+seen in reports.
+Forecast transactions begin the day after the latest recorded journal
+transaction (or today, if there are no transactions) and end 6 months
+from today (or at the report end date, if specified).
+.IP \[bu] 2
+With \f[C]\-\-budget\f[] (supported by the balance command), each
+periodic transaction rule declares recurring budget goals for the
+specified accounts, which can be seen in budget reports.
Eg the example above declares the goal of receiving $400 from
\f[C]income:acme\ inc\f[] (and also, depositing $400 into
\f[C]assets:bank:checking\f[]) every week.
.PP
-For more details, see: balance: Budgeting and Budgeting and Forecasting.
-.SH Automated postings
+(Actually, you can generate one\-off transactions too, by writing a
+period expression with no report interval.)
.PP
-Automated postings are postings added automatically by rule to certain
-transactions (with \f[C]\-\-auto\f[]).
+For more details, see: balance: Budget report and Cookbook: Budgeting
+and Forecasting.
+.SS Automated postings
+.PP
+Automated postings (enabled by \f[C]\-\-auto\f[]) are postings added
+automatically by rule to certain transactions.
An automated posting rule looks like a transaction where the first line
-is an equal sign (\f[C]=\f[]) followed by a query:
+is an equal sign (\f[C]=\f[]) followed by a query (mnemonic: \f[C]=\f[]
+tests for matching transactions, and also looks like posting lines):
.IP
.nf
\f[C]
@@ -1226,10 +1243,13 @@ transaction involving the \f[C]expenses:gifts\f[] account:
$\ hledger\ print\ \-\-auto
2017/12/14
\ \ \ \ expenses:gifts\ \ \ \ \ \ \ \ \ \ \ \ \ $20
-\ \ \ \ assets
\ \ \ \ (budget:gifts)\ \ \ \ \ \ \ \ \ \ \ \ $\-20
+\ \ \ \ assets
\f[]
.fi
+.PP
+Like postings recorded by hand, automated postings participate in
+transaction balancing, missing amount inference and balance assertions.
.SH EDITOR SUPPORT
.PP
Add\-on modes exist for various text editors, to make working with
diff --git a/embeddedfiles/hledger_journal.info b/embeddedfiles/hledger_journal.info
index b504424..51f0518 100644
--- a/embeddedfiles/hledger_journal.info
+++ b/embeddedfiles/hledger_journal.info
@@ -4,8 +4,8 @@ stdin.

File: hledger_journal.info, Node: Top, Next: FILE FORMAT, Up: (dir)
-hledger_journal(5) hledger 1.9
-******************************
+hledger_journal(5) hledger 1.9.1
+********************************
hledger's usual data source is a plain text file containing journal
entries in hledger journal format. This file represents a standard
@@ -57,12 +57,10 @@ assisted by the helper modes for emacs or vim.
* Menu:
* FILE FORMAT::
-* Periodic transactions::
-* Automated postings::
* EDITOR SUPPORT::

-File: hledger_journal.info, Node: FILE FORMAT, Next: Periodic transactions, Prev: Top, Up: Top
+File: hledger_journal.info, Node: FILE FORMAT, Next: EDITOR SUPPORT, Prev: Top, Up: Top
1 FILE FORMAT
*************
@@ -83,6 +81,8 @@ File: hledger_journal.info, Node: FILE FORMAT, Next: Periodic transactions, P
* Comments::
* Tags::
* Directives::
+* Periodic transactions::
+* Automated postings::

File: hledger_journal.info, Node: Transactions, Next: Postings, Up: FILE FORMAT
@@ -713,10 +713,6 @@ star ('*') are comments, and will be ignored. (Star comments cause
org-mode nodes to be ignored, allowing emacs users to fold and navigate
their journals with org-mode or orgstruct-mode.)
- Also, anything between 'comment' and 'end comment' directives is a
-(multi-line) comment. If there is no 'end comment', the comment extends
-to the end of the file.
-
You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the
postings). Similarly, you can attach comments to an individual posting
@@ -744,6 +740,9 @@ end comment
; another comment line for posting 2
; a file comment (because not indented)
+ You can also comment larger regions of a file using 'comment' and
+'end comment' directives.
+

File: hledger_journal.info, Node: Tags, Next: Directives, Prev: Comments, Up: FILE FORMAT
@@ -788,27 +787,183 @@ example, the following transaction has three tags ('A', 'TAG2',
are simple strings.

-File: hledger_journal.info, Node: Directives, Prev: Tags, Up: FILE FORMAT
+File: hledger_journal.info, Node: Directives, Next: Periodic transactions, Prev: Tags, Up: FILE FORMAT
1.14 Directives
===============
* Menu:
-* Account aliases::
-* account directive::
-* apply account directive::
-* Multi-line comments::
-* commodity directive::
-* Default commodity::
-* Default year::
+* Comment blocks::
* Including other files::
+* Default year::
+* Declaring commodities::
+* Default commodity::
+* Declaring accounts::
+* Rewriting accounts::
+* Default parent account::
+
+
+File: hledger_journal.info, Node: Comment blocks, Next: Including other files, Up: Directives
+
+1.14.1 Comment blocks
+---------------------
+
+A line containing just 'comment' starts a commented region of the file,
+and a line containing just 'end comment' (or the end of the current
+file) ends it. See also comments.
+
+
+File: hledger_journal.info, Node: Including other files, Next: Default year, Prev: Comment blocks, Up: Directives
+
+1.14.2 Including other files
+----------------------------
+
+You can pull in the content of additional files by writing an include
+directive, like this:
+
+include path/to/file.journal
+
+ If the path does not begin with a slash, it is relative to the
+current file. Glob patterns ('*') are not currently supported.
+
+ The 'include' directive can only be used in journal files. It can
+include journal, timeclock or timedot files, but not CSV files.
+
+
+File: hledger_journal.info, Node: Default year, Next: Declaring commodities, Prev: Including other files, Up: Directives
+
+1.14.3 Default year
+-------------------
+
+You can set a default year to be used for subsequent dates which don't
+specify a year. This is a line beginning with 'Y' followed by the year.
+Eg:
+
+Y2009 ; set default year to 2009
+
+12/15 ; equivalent to 2009/12/15
+ expenses 1
+ assets
+
+Y2010 ; change default year to 2010
+
+2009/1/30 ; specifies the year, not affected
+ expenses 1
+ assets
+
+1/31 ; equivalent to 2010/1/31
+ expenses 1
+ assets

-File: hledger_journal.info, Node: Account aliases, Next: account directive, Up: Directives
+File: hledger_journal.info, Node: Declaring commodities, Next: Default commodity, Prev: Default year, Up: Directives
+
+1.14.4 Declaring commodities
+----------------------------
-1.14.1 Account aliases
-----------------------
+The 'commodity' directive declares commodities which may be used in the
+journal (though currently we do not enforce this). It may be written on
+a single line, like this:
+
+; commodity EXAMPLEAMOUNT
+
+; display AAAA amounts with the symbol on the right, space-separated,
+; using period as decimal point, with four decimal places, and
+; separating thousands with comma.
+commodity 1,000.0000 AAAA
+
+ or on multiple lines, using the "format" subdirective. In this case
+the commodity symbol appears twice and should be the same in both
+places:
+
+; commodity SYMBOL
+; format EXAMPLEAMOUNT
+
+; 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 9,99,99,999.00
+
+ Commodity directives have a second purpose: they define the standard
+display format for amounts in the commodity. Normally the display
+format is inferred from journal entries, but this can be unpredictable;
+declaring it with a commodity directive overrides this and removes
+ambiguity. Towards this end, amounts in commodity directives must
+always be written with a decimal point (a period or comma, followed by 0
+or more decimal digits).
+
+
+File: hledger_journal.info, Node: Default commodity, Next: Declaring accounts, Prev: Declaring commodities, Up: Directives
+
+1.14.5 Default commodity
+------------------------
+
+The D directive sets a default commodity (and display format), to be
+used for amounts without a commodity symbol (ie, plain numbers). (Note
+this differs from Ledger's default commodity directive.) The commodity
+and display format will be applied to all subsequent commodity-less
+amounts, or until the next D directive.
+
+# commodity-less amounts should be treated as dollars
+# (and displayed with symbol on the left, thousands separators and two decimal places)
+D $1,000.00
+
+1/1
+ a 5 ; <- commodity-less amount, becomes $1
+ b
+
+ As with the 'commodity' directive, the amount must always be written
+with a decimal point.
+
+
+File: hledger_journal.info, Node: Declaring accounts, Next: Rewriting accounts, Prev: Default commodity, Up: Directives
+
+1.14.6 Declaring accounts
+-------------------------
+
+The 'account' directive predeclares account names. The simplest form is
+'account ACCTNAME', eg:
+
+account assets:bank:checking
+
+ Currently this mainly helps with account name autocompletion in eg
+hledger add, hledger-iadd, hledger-web, and ledger-mode.
+In future it will also help detect misspelled accounts.
+
+ Account names can be followed by a numeric account code:
+
+account assets 1000
+account assets:bank:checking 1110
+account liabilities 2000
+account revenues 4000
+account expenses 6000
+
+ This affects account display order in reports: accounts with codes
+are listed before accounts without codes, in increasing code order.
+(Otherwise, accounts are listed alphabetically.) Account codes should
+be all numeric digits, unique, and separated from the account name by at
+least two spaces (since account names may contain single spaces). By
+convention, often the first digit indicates the type of account, as in
+this numbering scheme and the example above. In future, we might use
+this to recognize account types.
+
+ An account directive can also have indented subdirectives following
+it, which are currently ignored. Here is the full syntax:
+
+; account ACCTNAME [OPTIONALCODE]
+; [OPTIONALSUBDIRECTIVES]
+
+account assets:bank:checking 1110
+ a comment
+ some-tag:12345
+
+
+File: hledger_journal.info, Node: Rewriting accounts, Next: Default parent account, Prev: Declaring accounts, Up: Directives
+
+1.14.7 Rewriting accounts
+-------------------------
You can define aliases which rewrite your account names (after reading
the journal, before generating reports). hledger's account aliases can
@@ -821,7 +976,7 @@ be useful for:
or combining two accounts into one
* customising reports
- See also Cookbook: rewrite account names.
+ See also Cookbook: Rewrite account names.
* Menu:
* Basic aliases::
@@ -830,9 +985,9 @@ be useful for:
* end aliases::

-File: hledger_journal.info, Node: Basic aliases, Next: Regex aliases, Up: Account aliases
+File: hledger_journal.info, Node: Basic aliases, Next: Regex aliases, Up: Rewriting accounts
-1.14.1.1 Basic aliases
+1.14.7.1 Basic aliases
......................
To set an account alias, use the 'alias' directive in your journal file.
@@ -853,9 +1008,9 @@ 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_journal.info, Node: Regex aliases, Next: Multiple aliases, Prev: Basic aliases, Up: Account aliases
+File: hledger_journal.info, Node: Regex aliases, Next: Multiple aliases, Prev: Basic aliases, Up: Rewriting accounts
-1.14.1.2 Regex aliases
+1.14.7.2 Regex aliases
......................
There is also a more powerful variant that uses a regular expression,
@@ -878,9 +1033,9 @@ command line, to end of option argument), so it can contain trailing
whitespace.

-File: hledger_journal.info, Node: Multiple aliases, Next: end aliases, Prev: Regex aliases, Up: Account aliases
+File: hledger_journal.info, Node: Multiple aliases, Next: end aliases, Prev: Regex aliases, Up: Rewriting accounts
-1.14.1.3 Multiple aliases
+1.14.7.3 Multiple aliases
.........................
You can define as many aliases as you like using directives or
@@ -894,10 +1049,10 @@ following order:
2. alias options, in the order they appear on the command line

-File: hledger_journal.info, Node: end aliases, Prev: Multiple aliases, Up: Account aliases
+File: hledger_journal.info, Node: end aliases, Prev: Multiple aliases, Up: Rewriting accounts
-1.14.1.4 end aliases
-....................
+1.14.7.4 'end aliases'
+......................
You can clear (forget) all currently defined aliases with the 'end
aliases' directive:
@@ -905,52 +1060,10 @@ aliases' directive:
end aliases

-File: hledger_journal.info, Node: account directive, Next: apply account directive, Prev: Account aliases, Up: Directives
-
-1.14.2 account directive
-------------------------
-
-The 'account' directive predeclares account names. The simplest form is
-'account ACCTNAME', eg:
-
-account assets:bank:checking
-
- Currently this mainly helps with account name autocompletion in eg
-hledger add, hledger-iadd, hledger-web, and ledger-mode.
-In future it will also help detect misspelled accounts.
-
- Account names can be followed by a numeric account code:
+File: hledger_journal.info, Node: Default parent account, Prev: Rewriting accounts, Up: Directives
-account assets 1000
-account assets:bank:checking 1110
-account liabilities 2000
-account revenues 4000
-account expenses 6000
-
- This affects account display order in reports: accounts with codes
-are listed before accounts without codes, in increasing code order.
-(Otherwise, accounts are listed alphabetically.) Account codes should
-be all numeric digits, unique, and separated from the account name by at
-least two spaces (since account names may contain single spaces). By
-convention, often the first digit indicates the type of account, as in
-this numbering scheme and the example above. In future, we might use
-this to recognize account types.
-
- An account directive can also have indented subdirectives following
-it, which are currently ignored. Here is the full syntax:
-
-; account ACCTNAME [OPTIONALCODE]
-; [OPTIONALSUBDIRECTIVES]
-
-account assets:bank:checking 1110
- a comment
- some-tag:12345
-
-
-File: hledger_journal.info, Node: apply account directive, Next: Multi-line comments, Prev: account directive, Up: Directives
-
-1.14.3 apply account directive
-------------------------------
+1.14.8 Default parent account
+-----------------------------
You can specify a parent account which will be prepended to all accounts
within a section of the journal. Use the 'apply account' and 'end apply
@@ -983,148 +1096,52 @@ include personal.journal
supported.

-File: hledger_journal.info, Node: Multi-line comments, Next: commodity directive, Prev: apply account directive, Up: Directives
-
-1.14.4 Multi-line comments
---------------------------
-
-A line containing just 'comment' starts a multi-line comment, and a line
-containing just 'end comment' ends it. See comments.
-
-
-File: hledger_journal.info, Node: commodity directive, Next: Default commodity, Prev: Multi-line comments, Up: Directives
-
-1.14.5 commodity directive
---------------------------
-
-The 'commodity' directive predefines commodities (currently this is just
-informational), and also it may define the display format for amounts in
-this commodity (overriding the automatically inferred format).
-
- It may be written on a single line, like this:
-
-; commodity EXAMPLEAMOUNT
-
-; display AAAA amounts with the symbol on the right, space-separated,
-; using period as decimal point, with four decimal places, and
-; separating thousands with comma.
-commodity 1,000.0000 AAAA
-
- or on multiple lines, using the "format" subdirective. In this case
-the commodity symbol appears twice and should be the same in both
-places:
-
-; commodity SYMBOL
-; format EXAMPLEAMOUNT
-
-; 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 9,99,99,999.00
-
-
-File: hledger_journal.info, Node: Default commodity, Next: Default year, Prev: commodity directive, Up: Directives
-
-1.14.6 Default commodity
-------------------------
-
-The D directive sets a default commodity (and display format), to be
-used for amounts without a commodity symbol (ie, plain numbers). (Note
-this differs from Ledger's default commodity directive.) The commodity
-and display format will be applied to all subsequent commodity-less
-amounts, or until the next D directive.
-
-# commodity-less amounts should be treated as dollars
-# (and displayed with symbol on the left, thousands separators and two decimal places)
-D $1,000.00
-
-1/1
- a 5 ; <- commodity-less amount, becomes $1
- b
-
-
-File: hledger_journal.info, Node: Default year, Next: Including other files, Prev: Default commodity, Up: Directives
+File: hledger_journal.info, Node: Periodic transactions, Next: Automated postings, Prev: Directives, Up: FILE FORMAT
-1.14.7 Default year
--------------------
+1.15 Periodic transactions
+==========================
-You can set a default year to be used for subsequent dates which don't
-specify a year. This is a line beginning with 'Y' followed by the year.
-Eg:
-
-Y2009 ; set default year to 2009
-
-12/15 ; equivalent to 2009/12/15
- expenses 1
- assets
-
-Y2010 ; change default year to 2010
-
-2009/1/30 ; specifies the year, not affected
- expenses 1
- assets
-
-1/31 ; equivalent to 2010/1/31
- expenses 1
- assets
-
-
-File: hledger_journal.info, Node: Including other files, Prev: Default year, Up: Directives
-
-1.14.8 Including other files
-----------------------------
-
-You can pull in the content of additional journal files by writing an
-include directive, like this:
-
-include path/to/file.journal
-
- If the path does not begin with a slash, it is relative to the
-current file. Glob patterns ('*') are not currently supported.
-
- The 'include' directive can only be used in journal files. It can
-include journal, timeclock or timedot files, but not CSV files.
-
-
-File: hledger_journal.info, Node: Periodic transactions, Next: Automated postings, Prev: FILE FORMAT, Up: Top
-
-2 Periodic transactions
-***********************
-
-Periodic transactions are a kind of rule with a dual purpose: they can
-specify recurring future transactions (with '--forecast'), or budget
-goals (with '--budget'). They look a bit like a transaction, except the
-first line is a tilde ('~') followed by a period expression:
+Periodic transaction rules (enabled by '--forecast' or '--budget')
+describe recurring transactions. They look like a transaction where the
+first line is a tilde ('~') followed by a period expression (mnemonic:
+'~' is like a recurring sine wave):
~ weekly
assets:bank:checking $400 ; paycheck
income:acme inc
- With '--forecast', each periodic transaction rule generates recurring
-"forecast" transactions at the specified interval, beginning the day
-after the latest recorded journal transaction (or today, if there are no
-transactions) and ending 6 months from today (or at the report end date,
-if specified).
+ Periodic transactions have a dual purpose:
+
+ * With '--forecast', each periodic transaction rule generates future
+ transactions, recurring at the specified interval, which can be
+ seen in reports. Forecast transactions begin the day after the
+ latest recorded journal transaction (or today, if there are no
+ transactions) and end 6 months from today (or at the report end
+ date, if specified).
- With 'balance --budget', each periodic transaction declares recurring
-budget goals for the specified accounts. Eg the example above declares
-the goal of receiving $400 from 'income:acme inc' (and also, depositing
-$400 into 'assets:bank:checking') every week.
+ * With '--budget' (supported by the balance command), each periodic
+ transaction rule declares recurring budget goals for the specified
+ accounts, which can be seen in budget reports. Eg the example
+ above declares the goal of receiving $400 from 'income:acme inc'
+ (and also, depositing $400 into 'assets:bank:checking') every week.
- For more details, see: balance: Budgeting and Budgeting and
-Forecasting.
+ (Actually, you can generate one-off transactions too, by writing a
+period expression with no report interval.)
+
+ For more details, see: balance: Budget report and Cookbook: Budgeting
+and Forecasting.

-File: hledger_journal.info, Node: Automated postings, Next: EDITOR SUPPORT, Prev: Periodic transactions, Up: Top
+File: hledger_journal.info, Node: Automated postings, Prev: Periodic transactions, Up: FILE FORMAT
-3 Automated postings
-********************
+1.16 Automated postings
+=======================
-Automated postings are postings added automatically by rule to certain
-transactions (with '--auto'). An automated posting rule looks like a
-transaction where the first line is an equal sign ('=') followed by a
-query:
+Automated postings (enabled by '--auto') are postings added
+automatically by rule to certain transactions. An automated posting
+rule looks like a transaction where the first line is an equal sign
+('=') followed by a query (mnemonic: '=' tests for matching
+transactions, and also looks like posting lines):
= expenses:gifts
budget:gifts *-1
@@ -1149,13 +1166,16 @@ every transaction involving the 'expenses:gifts' account:
$ hledger print --auto
2017/12/14
expenses:gifts $20
- assets
(budget:gifts) $-20
+ assets
+
+ Like postings recorded by hand, automated postings participate in
+transaction balancing, missing amount inference and balance assertions.

-File: hledger_journal.info, Node: EDITOR SUPPORT, Prev: Automated postings, Up: Top
+File: hledger_journal.info, Node: EDITOR SUPPORT, Prev: FILE FORMAT, Up: Top
-4 EDITOR SUPPORT
+2 EDITOR SUPPORT
****************
Add-on modes exist for various text editors, to make working with
@@ -1182,89 +1202,89 @@ Code

Tag Table:
Node: Top76
-Node: FILE FORMAT2419
-Ref: #file-format2550
-Node: Transactions2773
-Ref: #transactions2894
-Node: Postings3578
-Ref: #postings3705
-Node: Dates4700
-Ref: #dates4815
-Node: Simple dates4880
-Ref: #simple-dates5006
-Node: Secondary dates5372
-Ref: #secondary-dates5526
-Node: Posting dates7089
-Ref: #posting-dates7218
-Node: Status8592
-Ref: #status8712
-Node: Description10420
-Ref: #description10558
-Node: Payee and note10877
-Ref: #payee-and-note10991
-Node: Account names11233
-Ref: #account-names11376
-Node: Amounts11863
-Ref: #amounts11999
-Node: Virtual Postings15014
-Ref: #virtual-postings15173
-Node: Balance Assertions16393
-Ref: #balance-assertions16568
-Node: Assertions and ordering17464
-Ref: #assertions-and-ordering17650
-Node: Assertions and included files18350
-Ref: #assertions-and-included-files18591
-Node: Assertions and multiple -f options18924
-Ref: #assertions-and-multiple--f-options19178
-Node: Assertions and commodities19310
-Ref: #assertions-and-commodities19545
-Node: Assertions and subaccounts20241
-Ref: #assertions-and-subaccounts20473
-Node: Assertions and virtual postings20994
-Ref: #assertions-and-virtual-postings21201
-Node: Balance Assignments21343
-Ref: #balance-assignments21512
-Node: Prices22632
-Ref: #prices22765
-Node: Transaction prices22816
-Ref: #transaction-prices22961
-Node: Market prices25117
-Ref: #market-prices25252
-Node: Comments26212
-Ref: #comments26334
-Node: Tags27576
-Ref: #tags27694
-Node: Directives29096
-Ref: #directives29209
-Node: Account aliases29402
-Ref: #account-aliases29546
-Node: Basic aliases30150
-Ref: #basic-aliases30293
-Node: Regex aliases30983
-Ref: #regex-aliases31151
-Node: Multiple aliases31869
-Ref: #multiple-aliases32041
-Node: end aliases32539
-Ref: #end-aliases32679
-Node: account directive32780
-Ref: #account-directive32960
-Node: apply account directive34307
-Ref: #apply-account-directive34503
-Node: Multi-line comments35162
-Ref: #multi-line-comments35352
-Node: commodity directive35480
-Ref: #commodity-directive35664
-Node: Default commodity36536
-Ref: #default-commodity36709
-Node: Default year37246
-Ref: #default-year37411
-Node: Including other files37834
-Ref: #including-other-files37991
-Node: Periodic transactions38388
-Ref: #periodic-transactions38554
-Node: Automated postings39543
-Ref: #automated-postings39706
-Node: EDITOR SUPPORT40608
-Ref: #editor-support40733
+Node: FILE FORMAT2374
+Ref: #file-format2498
+Node: Transactions2770
+Ref: #transactions2891
+Node: Postings3575
+Ref: #postings3702
+Node: Dates4697
+Ref: #dates4812
+Node: Simple dates4877
+Ref: #simple-dates5003
+Node: Secondary dates5369
+Ref: #secondary-dates5523
+Node: Posting dates7086
+Ref: #posting-dates7215
+Node: Status8589
+Ref: #status8709
+Node: Description10417
+Ref: #description10555
+Node: Payee and note10874
+Ref: #payee-and-note10988
+Node: Account names11230
+Ref: #account-names11373
+Node: Amounts11860
+Ref: #amounts11996
+Node: Virtual Postings15011
+Ref: #virtual-postings15170
+Node: Balance Assertions16390
+Ref: #balance-assertions16565
+Node: Assertions and ordering17461
+Ref: #assertions-and-ordering17647
+Node: Assertions and included files18347
+Ref: #assertions-and-included-files18588
+Node: Assertions and multiple -f options18921
+Ref: #assertions-and-multiple--f-options19175
+Node: Assertions and commodities19307
+Ref: #assertions-and-commodities19542
+Node: Assertions and subaccounts20238
+Ref: #assertions-and-subaccounts20470
+Node: Assertions and virtual postings20991
+Ref: #assertions-and-virtual-postings21198
+Node: Balance Assignments21340
+Ref: #balance-assignments21509
+Node: Prices22629
+Ref: #prices22762
+Node: Transaction prices22813
+Ref: #transaction-prices22958
+Node: Market prices25114
+Ref: #market-prices25249
+Node: Comments26209
+Ref: #comments26331
+Node: Tags27501
+Ref: #tags27619
+Node: Directives29021
+Ref: #directives29164
+Node: Comment blocks29357
+Ref: #comment-blocks29502
+Node: Including other files29678
+Ref: #including-other-files29858
+Node: Default year30247
+Ref: #default-year30416
+Node: Declaring commodities30839
+Ref: #declaring-commodities31022
+Node: Default commodity32249
+Ref: #default-commodity32430
+Node: Declaring accounts33062
+Ref: #declaring-accounts33242
+Node: Rewriting accounts34589
+Ref: #rewriting-accounts34774
+Node: Basic aliases35378
+Ref: #basic-aliases35524
+Node: Regex aliases36214
+Ref: #regex-aliases36385
+Node: Multiple aliases37103
+Ref: #multiple-aliases37278
+Node: end aliases37776
+Ref: #end-aliases37923
+Node: Default parent account38024
+Ref: #default-parent-account38190
+Node: Periodic transactions38849
+Ref: #periodic-transactions39028
+Node: Automated postings40327
+Ref: #automated-postings40481
+Node: EDITOR SUPPORT41614
+Ref: #editor-support41732

End Tag Table
diff --git a/embeddedfiles/hledger_journal.txt b/embeddedfiles/hledger_journal.txt
index 485f4d2..dc6e261 100644
--- a/embeddedfiles/hledger_journal.txt
+++ b/embeddedfiles/hledger_journal.txt
@@ -553,10 +553,6 @@ FILE FORMAT
nodes to be ignored, allowing emacs users to fold and navigate their
journals with org-mode or orgstruct-mode.)
- Also, anything between comment and end comment directives is a
- (multi-line) comment. If there is no end comment, the comment extends
- to the end of the file.
-
You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the post-
ings). Similarly, you can attach comments to an individual posting by
@@ -584,21 +580,24 @@ FILE FORMAT
; another comment line for posting 2
; a file comment (because not indented)
+ You can also comment larger regions of a file using comment and
+ end comment directives.
+
Tags
- Tags are a way to add extra labels or labelled data to postings and
+ Tags are a way to add extra labels or labelled data to postings and
transactions, which you can then search or pivot on.
- A simple tag is a word (which may contain hyphens) followed by a full
+ A simple tag is a word (which may contain hyphens) followed by a full
colon, written inside a transaction or posting comment line:
2017/1/16 bought groceries ; sometag:
- Tags can have a value, which is the text after the colon, up to the
+ Tags can have a value, which is the text after the colon, up to the
next comma or end of line, with leading/trailing whitespace removed:
expenses:food $10 ; a-posting-tag: the tag value
- Note this means hledger's tag values can not contain commas or new-
+ Note this means hledger's tag values can not contain commas or new-
lines. Ending at commas means you can write multiple short tags on one
line, comma separated:
@@ -612,21 +611,147 @@ FILE FORMAT
o "tag2" is another tag, whose value is "some value ..."
- Tags in a transaction comment affect the transaction and all of its
- postings, while tags in a posting comment affect only that posting.
- For example, the following transaction has three tags (A, TAG2,
+ Tags in a transaction comment affect the transaction and all of its
+ postings, while tags in a posting comment affect only that posting.
+ For example, the following transaction has three tags (A, TAG2,
third-tag) and the posting has four (those plus posting-tag):
1/1 a transaction ; A:, TAG2:
; third-tag: a third transaction tag, <- with a value
(a) $1 ; posting-tag:
- Tags are like Ledger's metadata feature, except hledger's tag values
+ Tags are like Ledger's metadata feature, except hledger's tag values
are simple strings.
Directives
- Account aliases
- You can define aliases which rewrite your account names (after reading
+ Comment blocks
+ A line containing just comment starts a commented region of the file,
+ and a line containing just end comment (or the end of the current file)
+ ends it. See also comments.
+
+ Including other files
+ You can pull in the content of additional files by writing an include
+ directive, like this:
+
+ include path/to/file.journal
+
+ If the path does not begin with a slash, it is relative to the current
+ file. Glob patterns (*) are not currently supported.
+
+ The include directive can only be used in journal files. It can
+ include journal, timeclock or timedot files, but not CSV files.
+
+ Default year
+ You can set a default year to be used for subsequent dates which don't
+ specify a year. This is a line beginning with Y followed by the year.
+ Eg:
+
+ Y2009 ; set default year to 2009
+
+ 12/15 ; equivalent to 2009/12/15
+ expenses 1
+ assets
+
+ Y2010 ; change default year to 2010
+
+ 2009/1/30 ; specifies the year, not affected
+ expenses 1
+ assets
+
+ 1/31 ; equivalent to 2010/1/31
+ expenses 1
+ assets
+
+ Declaring commodities
+ The commodity directive declares commodities which may be used in the
+ journal (though currently we do not enforce this). It may be written
+ on a single line, like this:
+
+ ; commodity EXAMPLEAMOUNT
+
+ ; display AAAA amounts with the symbol on the right, space-separated,
+ ; using period as decimal point, with four decimal places, and
+ ; separating thousands with comma.
+ commodity 1,000.0000 AAAA
+
+ or on multiple lines, using the "format" subdirective. In this case
+ the commodity symbol appears twice and should be the same in both
+ places:
+
+ ; commodity SYMBOL
+ ; format EXAMPLEAMOUNT
+
+ ; 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 9,99,99,999.00
+
+ Commodity directives have a second purpose: they define the standard
+ display format for amounts in the commodity. Normally the display for-
+ mat is inferred from journal entries, but this can be unpredictable;
+ declaring it with a commodity directive overrides this and removes
+ ambiguity. Towards this end, amounts in commodity directives must
+ always be written with a decimal point (a period or comma, followed by
+ 0 or more decimal digits).
+
+ Default commodity
+ The D directive sets a default commodity (and display format), to be
+ used for amounts without a commodity symbol (ie, plain numbers). (Note
+ this differs from Ledger's default commodity directive.) The commodity
+ and display format will be applied to all subsequent commodity-less
+ amounts, or until the next D directive.
+
+ # commodity-less amounts should be treated as dollars
+ # (and displayed with symbol on the left, thousands separators and two decimal places)
+ D $1,000.00
+
+ 1/1
+ a 5 ; <- commodity-less amount, becomes $1
+ b
+
+ As with the commodity directive, the amount must always be written with
+ a decimal point.
+
+ Declaring accounts
+ The account directive predeclares account names. The simplest form is
+ account ACCTNAME, eg:
+
+ account assets:bank:checking
+
+ Currently this mainly helps with account name autocompletion in eg
+ hledger add, hledger-iadd, hledger-web, and ledger-mode.
+ In future it will also help detect misspelled accounts.
+
+ Account names can be followed by a numeric account code:
+
+ account assets 1000
+ account assets:bank:checking 1110
+ account liabilities 2000
+ account revenues 4000
+ account expenses 6000
+
+ This affects account display order in reports: accounts with codes are
+ listed before accounts without codes, in increasing code order. (Oth-
+ erwise, accounts are listed alphabetically.) Account codes should be
+ all numeric digits, unique, and separated from the account name by at
+ least two spaces (since account names may contain single spaces). By
+ convention, often the first digit indicates the type of account, as in
+ this numbering scheme and the example above. In future, we might use
+ this to recognize account types.
+
+ An account directive can also have indented subdirectives following it,
+ which are currently ignored. Here is the full syntax:
+
+ ; account ACCTNAME [OPTIONALCODE]
+ ; [OPTIONALSUBDIRECTIVES]
+
+ account assets:bank:checking 1110
+ a comment
+ some-tag:12345
+
+ Rewriting accounts
+ You can define aliases which rewrite your account names (after reading
the journal, before generating reports). hledger's account aliases can
be useful for:
@@ -640,11 +765,11 @@ FILE FORMAT
o customising reports
- See also Cookbook: rewrite account names.
+ See also Cookbook: 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
+ 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. The spaces around the = are optional:
alias OLD = NEW
@@ -652,91 +777,54 @@ FILE FORMAT
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 full account names. hledger will replace any occur-
- rence of the old account name with the new one. Subaccounts are also
+ OLD and NEW are full account names. hledger will replace any occur-
+ rence 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"
Regex aliases
- There is also a more powerful variant that uses a regular expression,
+ There is also a more powerful variant that uses a regular expression,
indicated by the forward slashes:
alias /REGEX/ = REPLACEMENT
or --alias '/REGEX/=REPLACEMENT'.
- REGEX is a case-insensitive regular expression. Anywhere it matches
- inside an account name, the matched part will be replaced by REPLACE-
- MENT. If REGEX contains parenthesised match groups, these can be ref-
+ REGEX is a case-insensitive regular expression. Anywhere it matches
+ inside an account name, the matched part will be replaced by REPLACE-
+ MENT. If REGEX contains parenthesised match groups, these can be ref-
erenced by the usual numeric backreferences in REPLACEMENT. Eg:
alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
- Also note that REPLACEMENT continues to the end of line (or on command
- line, to end of option argument), so it can contain trailing white-
+ Also note that REPLACEMENT continues to the end of line (or on command
+ line, to end of option argument), so it can contain trailing white-
space.
Multiple aliases
- You can define as many aliases as you like using directives or com-
- mand-line options. Aliases are recursive - each alias sees the result
- of applying previous ones. (This is different from Ledger, where
+ You can define as many aliases as you like using directives or com-
+ mand-line options. Aliases are recursive - each alias sees the result
+ of applying previous ones. (This is different from Ledger, where
aliases are non-recursive by default). Aliases are applied in the fol-
lowing order:
- 1. alias directives, most recently seen first (recent directives take
+ 1. alias directives, most recently seen first (recent directives take
precedence over earlier ones; directives not yet seen are ignored)
2. alias options, in the order they appear on the command line
end aliases
- You can clear (forget) all currently defined aliases with the
+ You can clear (forget) all currently defined aliases with the
end aliases directive:
end aliases
- account directive
- The account directive predeclares account names. The simplest form is
- account ACCTNAME, eg:
-
- account assets:bank:checking
-
- Currently this mainly helps with account name autocompletion in eg
- hledger add, hledger-iadd, hledger-web, and ledger-mode.
- In future it will also help detect misspelled accounts.
-
- Account names can be followed by a numeric account code:
-
- account assets 1000
- account assets:bank:checking 1110
- account liabilities 2000
- account revenues 4000
- account expenses 6000
-
- This affects account display order in reports: accounts with codes are
- listed before accounts without codes, in increasing code order. (Oth-
- erwise, accounts are listed alphabetically.) Account codes should be
- all numeric digits, unique, and separated from the account name by at
- least two spaces (since account names may contain single spaces). By
- convention, often the first digit indicates the type of account, as in
- this numbering scheme and the example above. In future, we might use
- this to recognize account types.
-
- An account directive can also have indented subdirectives following it,
- which are currently ignored. Here is the full syntax:
-
- ; account ACCTNAME [OPTIONALCODE]
- ; [OPTIONALSUBDIRECTIVES]
-
- account assets:bank:checking 1110
- a comment
- some-tag:12345
-
- apply account directive
- You can specify a parent account which will be prepended to all
- accounts within a section of the journal. Use the apply account and
+ Default parent account
+ You can specify a parent account which will be prepended to all
+ accounts within a section of the journal. Use the apply account and
end apply account directives like so:
apply account home
@@ -753,7 +841,7 @@ FILE FORMAT
home:food $10
home:cash $-10
- If end apply account is omitted, the effect lasts to the end of the
+ If end apply account is omitted, the effect lasts to the end of the
file. Included files are also affected, eg:
apply account business
@@ -762,129 +850,58 @@ FILE FORMAT
apply account personal
include personal.journal
- Prior to hledger 1.0, legacy account and end spellings were also sup-
+ Prior to hledger 1.0, legacy account and end spellings were also sup-
ported.
- Multi-line comments
- A line containing just comment starts a multi-line comment, and a line
- containing just end comment ends it. See comments.
-
- commodity directive
- The commodity directive predefines commodities (currently this is just
- informational), and also it may define the display format for amounts
- in this commodity (overriding the automatically inferred format).
-
- It may be written on a single line, like this:
-
- ; commodity EXAMPLEAMOUNT
-
- ; display AAAA amounts with the symbol on the right, space-separated,
- ; using period as decimal point, with four decimal places, and
- ; separating thousands with comma.
- commodity 1,000.0000 AAAA
-
- or on multiple lines, using the "format" subdirective. In this case
- the commodity symbol appears twice and should be the same in both
- places:
-
- ; commodity SYMBOL
- ; format EXAMPLEAMOUNT
-
- ; 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 9,99,99,999.00
-
- Default commodity
- The D directive sets a default commodity (and display format), to be
- used for amounts without a commodity symbol (ie, plain numbers). (Note
- this differs from Ledger's default commodity directive.) The commodity
- and display format will be applied to all subsequent commodity-less
- amounts, or until the next D directive.
-
- # commodity-less amounts should be treated as dollars
- # (and displayed with symbol on the left, thousands separators and two decimal places)
- D $1,000.00
-
- 1/1
- a 5 ; <- commodity-less amount, becomes $1
- b
-
- Default year
- You can set a default year to be used for subsequent dates which don't
- specify a year. This is a line beginning with Y followed by the year.
- Eg:
-
- Y2009 ; set default year to 2009
-
- 12/15 ; equivalent to 2009/12/15
- expenses 1
- assets
-
- Y2010 ; change default year to 2010
-
- 2009/1/30 ; specifies the year, not affected
- expenses 1
- assets
-
- 1/31 ; equivalent to 2010/1/31
- expenses 1
- assets
-
- Including other files
- You can pull in the content of additional journal files by writing an
- include directive, like this:
-
- include path/to/file.journal
-
- If the path does not begin with a slash, it is relative to the current
- file. Glob patterns (*) are not currently supported.
-
- The include directive can only be used in journal files. It can
- include journal, timeclock or timedot files, but not CSV files.
-
-Periodic transactions
- Periodic transactions are a kind of rule with a dual purpose: they can
- specify recurring future transactions (with --forecast), or budget
- goals (with --budget). They look a bit like a transaction, except the
- first line is a tilde (~) followed by a period expression:
+ Periodic transactions
+ Periodic transaction rules (enabled by --forecast or --budget) describe
+ recurring transactions. They look like a transaction where the first
+ line is a tilde (~) followed by a period expression (mnemonic: ~ is
+ like a recurring sine wave):
~ weekly
assets:bank:checking $400 ; paycheck
income:acme inc
- With --forecast, each periodic transaction rule generates recurring
- "forecast" transactions at the specified interval, beginning the day
- after the latest recorded journal transaction (or today, if there are
- no transactions) and ending 6 months from today (or at the report end
- date, if specified).
+ Periodic transactions have a dual purpose:
- With balance --budget, each periodic transaction declares recurring
- budget goals for the specified accounts. Eg the example above declares
- the goal of receiving $400 from income:acme inc (and also, depositing
- $400 into assets:bank:checking) every week.
+ o With --forecast, each periodic transaction rule generates future
+ transactions, recurring at the specified interval, which can be seen
+ in reports. Forecast transactions begin the day after the latest
+ recorded journal transaction (or today, if there are no transactions)
+ and end 6 months from today (or at the report end date, if speci-
+ fied).
- For more details, see: balance: Budgeting and Budgeting and Forecast-
- ing.
+ o With --budget (supported by the balance command), each periodic
+ transaction rule declares recurring budget goals for the specified
+ accounts, which can be seen in budget reports. Eg the example above
+ declares the goal of receiving $400 from income:acme inc (and also,
+ depositing $400 into assets:bank:checking) every week.
-Automated postings
- Automated postings are postings added automatically by rule to certain
- transactions (with --auto). An automated posting rule looks like a
- transaction where the first line is an equal sign (=) followed by a
- query:
+ (Actually, you can generate one-off transactions too, by writing a
+ period expression with no report interval.)
+
+ For more details, see: balance: Budget report and Cookbook: Budgeting
+ and Forecasting.
+
+ Automated postings
+ Automated postings (enabled by --auto) are postings added automatically
+ by rule to certain transactions. An automated posting rule looks like
+ a transaction where the first line is an equal sign (=) followed by a
+ query (mnemonic: = tests for matching transactions, and also looks like
+ posting lines):
= expenses:gifts
budget:gifts *-1
assets:budget *1
- The posting amounts can be of the form *N, which means "the amount of
- the matched transaction's first posting, multiplied by N". They can
+ The posting amounts can be of the form *N, which means "the amount of
+ the matched transaction's first posting, multiplied by N". They can
also be ordinary fixed amounts. Fixed amounts with no commodity symbol
- will be given the same commodity as the matched transaction's first
+ will be given the same commodity as the matched transaction's first
posting.
- This example adds a corresponding (unbalanced) budget posting to every
+ This example adds a corresponding (unbalanced) budget posting to every
transaction involving the expenses:gifts account:
= expenses:gifts
@@ -897,16 +914,19 @@ Automated postings
$ hledger print --auto
2017/12/14
expenses:gifts $20
- assets
(budget:gifts) $-20
+ assets
+
+ Like postings recorded by hand, automated postings participate in
+ transaction balancing, missing amount inference and balance assertions.
EDITOR SUPPORT
Add-on modes exist for various text editors, to make working with jour-
- nal files easier. They add colour, navigation aids and helpful com-
- mands. For hledger users who edit the journal file directly (the
+ nal files easier. They add colour, navigation aids and helpful com-
+ mands. For hledger users who edit the journal file directly (the
majority), using one of these modes is quite recommended.
- These were written with Ledger in mind, but also work with hledger
+ These were written with Ledger in mind, but also work with hledger
files:
@@ -925,7 +945,7 @@ EDITOR SUPPORT
REPORTING BUGS
- Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
+ Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list)
@@ -939,7 +959,7 @@ COPYRIGHT
SEE ALSO
- hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
+ hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)
@@ -947,4 +967,4 @@ SEE ALSO
-hledger 1.9 March 2018 hledger_journal(5)
+hledger 1.9.1 April 2018 hledger_journal(5)
diff --git a/embeddedfiles/hledger_timeclock.5 b/embeddedfiles/hledger_timeclock.5
index feb2a16..98f36e3 100644
--- a/embeddedfiles/hledger_timeclock.5
+++ b/embeddedfiles/hledger_timeclock.5
@@ -1,5 +1,5 @@
-.TH "hledger_timeclock" "5" "March 2018" "hledger 1.9" "hledger User Manuals"
+.TH "hledger_timeclock" "5" "April 2018" "hledger 1.9.1" "hledger User Manuals"
diff --git a/embeddedfiles/hledger_timeclock.info b/embeddedfiles/hledger_timeclock.info
index b521d40..780b0aa 100644
--- a/embeddedfiles/hledger_timeclock.info
+++ b/embeddedfiles/hledger_timeclock.info
@@ -4,8 +4,8 @@ stdin.

File: hledger_timeclock.info, Node: Top, Up: (dir)
-hledger_timeclock(5) hledger 1.9
-********************************
+hledger_timeclock(5) hledger 1.9.1
+**********************************
hledger can read timeclock files. As with Ledger, these are (a subset
of) timeclock.el's format, containing clock-in and clock-out entries as
diff --git a/embeddedfiles/hledger_timeclock.txt b/embeddedfiles/hledger_timeclock.txt
index 0add1b2..d57f4f6 100644
--- a/embeddedfiles/hledger_timeclock.txt
+++ b/embeddedfiles/hledger_timeclock.txt
@@ -77,4 +77,4 @@ SEE ALSO
-hledger 1.9 March 2018 hledger_timeclock(5)
+hledger 1.9.1 April 2018 hledger_timeclock(5)
diff --git a/embeddedfiles/hledger_timedot.5 b/embeddedfiles/hledger_timedot.5
index 45f5e24..ea203c7 100644
--- a/embeddedfiles/hledger_timedot.5
+++ b/embeddedfiles/hledger_timedot.5
@@ -1,5 +1,5 @@
-.TH "hledger_timedot" "5" "March 2018" "hledger 1.9" "hledger User Manuals"
+.TH "hledger_timedot" "5" "April 2018" "hledger 1.9.1" "hledger User Manuals"
diff --git a/embeddedfiles/hledger_timedot.info b/embeddedfiles/hledger_timedot.info
index 0b77c91..96268f9 100644
--- a/embeddedfiles/hledger_timedot.info
+++ b/embeddedfiles/hledger_timedot.info
@@ -4,8 +4,8 @@ stdin.

File: hledger_timedot.info, Node: Top, Next: FILE FORMAT, Up: (dir)
-hledger_timedot(5) hledger 1.9
-******************************
+hledger_timedot(5) hledger 1.9.1
+********************************
Timedot is a plain text format for logging dated, categorised quantities
(of time, usually), supported by hledger. It is convenient for
@@ -110,7 +110,7 @@ $ hledger -f t.timedot --alias /\\./=: bal date:2016/2/4

Tag Table:
Node: Top76
-Node: FILE FORMAT805
-Ref: #file-format906
+Node: FILE FORMAT809
+Ref: #file-format910

End Tag Table
diff --git a/embeddedfiles/hledger_timedot.txt b/embeddedfiles/hledger_timedot.txt
index 64eb4c7..6ba0028 100644
--- a/embeddedfiles/hledger_timedot.txt
+++ b/embeddedfiles/hledger_timedot.txt
@@ -124,4 +124,4 @@ SEE ALSO
-hledger 1.9 March 2018 hledger_timedot(5)
+hledger 1.9.1 April 2018 hledger_timedot(5)
diff --git a/hledger.1 b/hledger.1
index c4c2e6d..7f6ff87 100644
--- a/hledger.1
+++ b/hledger.1
@@ -1,6 +1,6 @@
.\"t
-.TH "hledger" "1" "March 2018" "hledger 1.9" "hledger User Manuals"
+.TH "hledger" "1" "April 2018" "hledger 1.9.1" "hledger User Manuals"
@@ -1096,13 +1096,11 @@ The following kinds of search terms can be used.
Remember these can also be prefixed with \f[B]\f[BC]not:\f[B]\f[], eg to
exclude a particular subaccount.
.TP
-.B \f[B]\f[BC]REGEX\f[B]\f[]
+.B \f[B]\f[BC]REGEX\f[B], \f[BC]acct:REGEX\f[B]\f[]
match account names by this regular expression.
-(No prefix is equivalent to \f[C]acct:\f[]).
+(With no prefix, \f[C]acct:\f[] is assumed.)
.RS
.RE
-.TP
-.B \f[B]\f[BC]acct:REGEX\f[B]\f[]
same as above
.RS
.RE
@@ -1514,8 +1512,35 @@ with \[en]budget, show unbudgeted accounts also
.RS
.RE
.PP
-The balance command displays accounts and balances.
-It is hledger's most featureful and versatile command.
+The balance command is hledger's most versatile command.
+Note, despite the name, it is not always used for showing real\-world
+account balances; the more accounting\-aware balancesheet and
+incomestatement may be more convenient for that.
+.PP
+By default, it displays all accounts, and each account's change in
+balance during the entire period of the journal.
+Balance changes are calculated by adding up the postings in each
+account.
+You can limit the postings matched, by a query, to see fewer accounts,
+changes over a different time period, changes from only cleared
+transactions, etc.
+.PP
+If you include an account's complete history of postings in the report,
+the balance change is equivalent to the account's current ending
+balance.
+For a real\-world account, typically you won't have all transactions in
+the journal; instead you'll have all transactions after a certain date,
+and an \[lq]opening balances\[rq] transaction setting the correct
+starting balance on that date.
+Then the balance command will show real\-world account balances.
+In some cases the \-H/\[en]historical flag is used to ensure this (more
+below).
+.PP
+The balance command can produce several styles of report:
+.SS Classic balance report
+.PP
+This is the original balance report, as found in Ledger.
+It usually looks like this:
.IP
.nf
\f[C]
@@ -1535,12 +1560,6 @@ $\ hledger\ balance
\f[]
.fi
.PP
-More precisely, the balance command shows the \f[I]change\f[] to each
-account's balance caused by all (matched) postings.
-In the common case where you do not filter by date and your journal sets
-the correct opening balances, this is the same as the account's ending
-balance.
-.PP
By default, accounts are displayed hierarchically, with subaccounts
indented below their parent.
At each level of the tree, accounts are sorted by account code if any,
@@ -1550,8 +1569,8 @@ Or with \f[C]\-S/\-\-sort\-amount\f[], by their balance amount.
\[lq]Boring\[rq] accounts, which contain a single interesting subaccount
and no balance of their own, are elided into the following line for more
compact output.
-(Not yet supported in tabular reports.) Use \f[C]\-\-no\-elide\f[] to
-prevent this.
+(Eg above, the \[lq]liabilities\[rq] account.) Use
+\f[C]\-\-no\-elide\f[] to prevent this.
.PP
Account balances are \[lq]inclusive\[rq] \- they include the balances of
any subaccounts.
@@ -1561,7 +1580,7 @@ omitted.
Use \f[C]\-E/\-\-empty\f[] to show them.
.PP
A final total is displayed by default; use \f[C]\-N/\-\-no\-total\f[] to
-suppress it:
+suppress it, eg:
.IP
.nf
\f[C]
@@ -1571,11 +1590,89 @@ $\ hledger\ balance\ \-p\ 2008/6\ expenses\ \-\-no\-total
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ \ \ supplies
\f[]
.fi
+.SS Customising the classic balance report
+.PP
+You can customise the layout of classic balance reports with
+\f[C]\-\-format\ FMT\f[]:
+.IP
+.nf
+\f[C]
+$\ hledger\ 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
+\f[]
+.fi
+.PP
+The FMT format string (plus a newline) specifies the formatting applied
+to each account/balance pair.
+It may contain any suitable text, with data fields interpolated like so:
+.PP
+\f[C]%[MIN][.MAX](FIELDNAME)\f[]
+.IP \[bu] 2
+MIN pads with spaces to at least this width (optional)
+.IP \[bu] 2
+MAX truncates at this width (optional)
+.IP \[bu] 2
+FIELDNAME must be enclosed in parentheses, and can be one of:
+.RS 2
+.IP \[bu] 2
+\f[C]depth_spacer\f[] \- a number of spaces equal to the account's
+depth, or if MIN is specified, MIN * depth spaces.
+.IP \[bu] 2
+\f[C]account\f[] \- the account's name
+.IP \[bu] 2
+\f[C]total\f[] \- the account's balance/posted total, right justified
+.RE
+.PP
+Also, FMT can begin with an optional prefix to control how
+multi\-commodity amounts are rendered:
+.IP \[bu] 2
+\f[C]%_\f[] \- render on multiple lines, bottom\-aligned (the default)
+.IP \[bu] 2
+\f[C]%^\f[] \- render on multiple lines, top\-aligned
+.IP \[bu] 2
+\f[C]%,\f[] \- render on one line, comma\-separated
+.PP
+There are some quirks.
+Eg in one\-line mode, \f[C]%(depth_spacer)\f[] has no effect, instead
+\f[C]%(account)\f[] has indentation built in.
+ Experimentation may be needed to get pleasing results.
+.PP
+Some example formats:
+.IP \[bu] 2
+\f[C]%(total)\f[] \- the account's total
+.IP \[bu] 2
+\f[C]%\-20.20(account)\f[] \- the account's name, left justified, padded
+to 20 characters and clipped at 20 characters
+.IP \[bu] 2
+\f[C]%,%\-50(account)\ \ %25(total)\f[] \- account name padded to 50
+characters, total padded to 20 characters, with multiple commodities
+rendered on one line
+.IP \[bu] 2
+\f[C]%20(total)\ \ %2(depth_spacer)%\-(account)\f[] \- the default
+format for the single\-column balance report
+.SS Colour support
+.PP
+The balance command shows negative amounts in red, if:
+.IP \[bu] 2
+the \f[C]TERM\f[] environment variable is not set to \f[C]dumb\f[]
+.IP \[bu] 2
+the output is not being redirected or piped anywhere
.SS Flat mode
.PP
-To see a flat list of full account names instead of the default
-hierarchical display, use \f[C]\-\-flat\f[].
-In this mode, accounts (unless depth\-clipped) show their
+To see a flat list instead of the default hierarchical display, use
+\f[C]\-\-flat\f[].
+In this mode, accounts (unless depth\-clipped) show their full names and
\[lq]exclusive\[rq] balance, excluding any subaccount balances.
In this mode, you can also use \f[C]\-\-drop\ N\f[] to omit the first
few account name components.
@@ -1589,26 +1686,32 @@ $\ hledger\ balance\ \-p\ 2008/6\ expenses\ \-N\ \-\-flat\ \-\-drop\ 1
.fi
.SS Depth limited balance reports
.PP
-With \f[C]\-\-depth\ N\f[], balance shows accounts only to the specified
-depth.
-This is very useful to show a complex charts of accounts in less detail.
-In flat mode, balances from accounts below the depth limit will be shown
-as part of a parent account at the depth limit.
+With \f[C]\-\-depth\ N\f[] or \f[C]depth:N\f[] or just \f[C]\-N\f[],
+balance reports show accounts only to the specified numeric depth.
+This is very useful to summarise a complex set of accounts and get an
+overview.
.IP
.nf
\f[C]
-$\ hledger\ balance\ \-N\ \-\-depth\ 1
+$\ hledger\ balance\ \-N\ \-1
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-1\ \ assets
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $2\ \ expenses
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-2\ \ income
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $1\ \ liabilities
\f[]
.fi
-.SS Multicolumn balance reports
.PP
-With a reporting interval, multiple balance columns will be shown, one
-for each report period.
-There are three types of multi\-column balance report, showing different
+Flat\-mode balance reports, which normally show exclusive balances, show
+inclusive balances at the depth limit.
+.SS Multicolumn balance report
+.PP
+Multicolumn or tabular balance reports are a very useful hledger
+feature, and usually the preferred style.
+They share many of the above features, but they show the report as a
+table, with columns representing time periods.
+This mode is activated by providing a reporting interval.
+.PP
+There are three types of multicolumn balance report, showing different
information:
.IP "1." 3
By default: each column shows the sum of postings in that period, ie the
@@ -1680,8 +1783,8 @@ Ending\ balances\ (historical)\ in\ 2008/04/01\-2008/12/31:
.fi
.RE
.PP
-Multi\-column balance reports display accounts in flat mode by default;
-to see the hierarchy, use \f[C]\-\-tree\f[].
+Multicolumn balance reports display accounts in flat mode by default; to
+see the hierarchy, use \f[C]\-\-tree\f[].
.PP
With a reporting interval (like \f[C]\-\-quarterly\f[] above), the
report start/end dates will be adjusted if necessary so that they
@@ -1725,13 +1828,23 @@ Balance\ changes\ in\ 2008:
#\ Average\ is\ rounded\ to\ the\ dollar\ here\ since\ all\ journal\ amounts\ are
\f[]
.fi
-.SS Budgets
.PP
-With \f[C]\-\-budget\f[] and a report interval, all periodic
-transactions in your journal with that interval, active during the
-requested report period, are interpreted as recurring budget goals for
-the specified accounts (and subaccounts), and the report will show the
-difference between actual and budgeted balances.
+Limitations:
+.PP
+In multicolumn reports the \f[C]\-V/\-\-value\f[] flag uses the market
+price on the report end date, for all columns (not the price on each
+column's end date).
+.PP
+Eliding of boring parent accounts in tree mode, as in the classic
+balance report, is not yet supported in multicolumn reports.
+.SS Budget report
+.PP
+With \f[C]\-\-budget\f[], extra columns are displayed showing budget
+goals for each account and period, if any.
+Budget goals are defined by periodic transactions.
+This is very useful for comparing planned and actual income, expenses,
+time usage, etc.
+\[en]budget is most often combined with a report interval.
.PP
For example, you can take average monthly expenses in the common expense
categories to construct a minimal monthly budget:
@@ -1764,156 +1877,61 @@ categories to construct a minimal monthly budget:
\f[]
.fi
.PP
-You can now see a monthly budget performance report:
+You can now see a monthly budget report:
.IP
.nf
\f[C]
$\ hledger\ balance\ \-M\ \-\-budget
-Balance\ changes\ in\ 2017/11/01\-2017/12/31:
-
-\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12\
-=======================++=================================================
-\ <unbudgeted>:expenses\ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $100\
-\ assets:bank:checking\ \ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-2665\ [107%\ of\ $\-2480]\
-\ expenses:bus\ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ \ \ $53\ [106%\ of\ $50]\
-\ expenses:food\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $412\ [103%\ of\ $400]\
-\ expenses:movies\ \ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ \ \ \ 0\ [0%\ of\ $30]\
-\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $2100\ [105%\ of\ $2000]\
-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
-\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\
-\f[]
-.fi
-.PP
-You can roll over unspent budgets to next period with
-\f[C]\-\-cumulative\f[]:
-.IP
-.nf
-\f[C]
-$\ hledger\ balance\ \-M\ \-\-budget\ \-\-cumulative
-Ending\ balances\ (cumulative)\ in\ 2017/11/01\-2017/12/31:
-
-\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11/30\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12/31\
-=======================++=================================================
-\ <unbudgeted>:expenses\ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $120\
-\ assets:bank:checking\ \ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-5110\ [103%\ of\ $\-4960]\
-\ expenses:bus\ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ $102\ [102%\ of\ $100]\
-\ expenses:food\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $808\ [101%\ of\ $800]\
-\ expenses:movies\ \ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ $30\ [50%\ of\ $60]\
-\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $4050\ [101%\ of\ $4000]\
-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
-\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0
-\f[]
-.fi
-.PP
-Accounts with no budget goals (not mentioned in the periodic
-transactions) will be aggregated under \f[C]<unbudgeted>\f[], unless you
-add the \f[C]\-\-show\-unbudgeted\f[] flag to display them normally:
-.IP
-.nf
-\f[C]
-$\ hledger\ balance\ \-\-budget\ \-\-show\-unbudgeted
-Balance\ changes\ in\ 2017/11/01\-2017/12/31:
+Budget\ performance\ in\ 2017/11/01\-2017/12/31:
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12\
======================++=================================================
+\ <unbudgeted>\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $100\
\ assets:bank:checking\ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-2665\ [107%\ of\ $\-2480]\
\ expenses:bus\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ \ \ $53\ [106%\ of\ $50]\
\ expenses:food\ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $412\ [103%\ of\ $400]\
-\ expenses:gifts\ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $100\
\ expenses:movies\ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ \ \ \ 0\ [0%\ of\ $30]\
-\ expenses:supplies\ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\
\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $2100\ [105%\ of\ $2000]\
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\
\f[]
.fi
.PP
-Note \[en]budget first arrived in hledger in 1.5 and is still pretty
-young; join the discussions on mail list and issue tracker to help us
-refine it.
-.PP
-For more examples, see Budgeting and Forecasting.
-.SS Custom balance output
+By default, only accounts with budget goals during the report period are
+shown.
+\f[C]\-\-show\-unbudgeted\f[] shows unbudgeted accounts as well.
+Top\-level accounts with no budget goals anywhere below them are grouped
+under \f[C]<unbudgeted>\f[].
.PP
-You can customise the layout of simple (non\-tabular) balance reports
-with \f[C]\-\-format\ FMT\f[]:
+You can roll over unspent budgets to next period with
+\f[C]\-\-cumulative\f[]:
.IP
.nf
\f[C]
-$\ hledger\ 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
+$\ hledger\ balance\ \-M\ \-\-budget\ \-\-cumulative
+Budget\ performance\ in\ 2017/11/01\-2017/12/31:
+
+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ 2017/11/30\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2017/12/31\
+======================++=================================================
+\ <unbudgeted>\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $120\
+\ assets:bank:checking\ ||\ $\-2445\ [99%\ of\ $\-2480]\ \ $\-5110\ [103%\ of\ $\-4960]\
+\ expenses:bus\ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ $49\ [98%\ of\ $50]\ \ \ \ \ \ $102\ [102%\ of\ $100]\
+\ expenses:food\ \ \ \ \ \ \ \ ||\ \ \ \ \ $396\ [99%\ of\ $400]\ \ \ \ \ \ $808\ [101%\ of\ $800]\
+\ expenses:movies\ \ \ \ \ \ ||\ \ \ \ \ \ $30\ [100%\ of\ $30]\ \ \ \ \ \ \ \ \ $30\ [50%\ of\ $60]\
+\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ $1950\ [98%\ of\ $2000]\ \ \ \ $4050\ [101%\ of\ $4000]\
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0
\f[]
.fi
.PP
-The FMT format string (plus a newline) specifies the formatting applied
-to each account/balance pair.
-It may contain any suitable text, with data fields interpolated like so:
+Note, the \f[C]\-S/\-\-sort\-amount\f[] flag is not yet fully supported
+with \f[C]\-\-budget\f[].
.PP
-\f[C]%[MIN][.MAX](FIELDNAME)\f[]
-.IP \[bu] 2
-MIN pads with spaces to at least this width (optional)
-.IP \[bu] 2
-MAX truncates at this width (optional)
-.IP \[bu] 2
-FIELDNAME must be enclosed in parentheses, and can be one of:
-.RS 2
-.IP \[bu] 2
-\f[C]depth_spacer\f[] \- a number of spaces equal to the account's
-depth, or if MIN is specified, MIN * depth spaces.
-.IP \[bu] 2
-\f[C]account\f[] \- the account's name
-.IP \[bu] 2
-\f[C]total\f[] \- the account's balance/posted total, right justified
-.RE
-.PP
-Also, FMT can begin with an optional prefix to control how
-multi\-commodity amounts are rendered:
-.IP \[bu] 2
-\f[C]%_\f[] \- render on multiple lines, bottom\-aligned (the default)
-.IP \[bu] 2
-\f[C]%^\f[] \- render on multiple lines, top\-aligned
-.IP \[bu] 2
-\f[C]%,\f[] \- render on one line, comma\-separated
-.PP
-There are some quirks.
-Eg in one\-line mode, \f[C]%(depth_spacer)\f[] has no effect, instead
-\f[C]%(account)\f[] has indentation built in.
- Experimentation may be needed to get pleasing results.
-.PP
-Some example formats:
-.IP \[bu] 2
-\f[C]%(total)\f[] \- the account's total
-.IP \[bu] 2
-\f[C]%\-20.20(account)\f[] \- the account's name, left justified, padded
-to 20 characters and clipped at 20 characters
-.IP \[bu] 2
-\f[C]%,%\-50(account)\ \ %25(total)\f[] \- account name padded to 50
-characters, total padded to 20 characters, with multiple commodities
-rendered on one line
-.IP \[bu] 2
-\f[C]%20(total)\ \ %2(depth_spacer)%\-(account)\f[] \- the default
-format for the single\-column balance report
+For more examples, see Budgeting and Forecasting.
+.SS Output format
.PP
-This command also supports output destination and output format
+The balance command supports output destination and output format
selection.
-.SS Colour support
-.PP
-The balance command shows negative amounts in red, if:
-.IP \[bu] 2
-the \f[C]TERM\f[] environment variable is not set to \f[C]dumb\f[]
-.IP \[bu] 2
-the output is not being redirected or piped anywhere
.SS balancesheet
.PP
This command displays a simple balance sheet, showing historical ending
diff --git a/hledger.cabal b/hledger.cabal
index a0eb65e..5123e33 100644
--- a/hledger.cabal
+++ b/hledger.cabal
@@ -1,11 +1,11 @@
--- This file has been generated from package.yaml by hpack version 0.20.0.
+-- This file has been generated from package.yaml by hpack version 0.28.2.
--
-- see: https://github.com/sol/hpack
--
--- hash: 99eb38f5627e64b90fe33622dba3444cfb4f1d57f69c12b19731fb061f2b896a
+-- hash: 43b8d8dfa1791a15d30d4e99714152b6bf36889a6038841e7d750f58a7cfede8
name: hledger
-version: 1.9
+version: 1.9.1
synopsis: Command-line interface for the hledger accounting tool
description: This is hledger's command-line interface.
Its basic function is to read a plain text file describing
@@ -28,7 +28,6 @@ license-file: LICENSE
tested-with: GHC==7.10.3, GHC==8.0.2, GHC==8.2.1
build-type: Simple
cabal-version: >= 1.10
-
extra-source-files:
bench/10000x1000x10.journal
CHANGES
@@ -77,8 +76,40 @@ flag threaded
default: True
library
+ exposed-modules:
+ Hledger.Cli
+ Hledger.Cli.Main
+ Hledger.Cli.CliOptions
+ Hledger.Cli.DocFiles
+ Hledger.Cli.Utils
+ Hledger.Cli.Version
+ Hledger.Cli.Commands
+ Hledger.Cli.Commands.Accounts
+ Hledger.Cli.Commands.Activity
+ Hledger.Cli.Commands.Add
+ Hledger.Cli.Commands.Balance
+ Hledger.Cli.Commands.Balancesheet
+ Hledger.Cli.Commands.Balancesheetequity
+ Hledger.Cli.Commands.Cashflow
+ Hledger.Cli.Commands.Checkdates
+ Hledger.Cli.Commands.Checkdupes
+ Hledger.Cli.Commands.Close
+ Hledger.Cli.Commands.Help
+ Hledger.Cli.Commands.Import
+ Hledger.Cli.Commands.Incomestatement
+ Hledger.Cli.Commands.Prices
+ Hledger.Cli.Commands.Print
+ Hledger.Cli.Commands.Printunique
+ Hledger.Cli.Commands.Register
+ Hledger.Cli.Commands.Registermatch
+ Hledger.Cli.Commands.Rewrite
+ Hledger.Cli.Commands.Stats
+ Hledger.Cli.Commands.Tags
+ Hledger.Cli.CompoundBalanceCommand
+ other-modules:
+ Paths_hledger
ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans -optP-Wno-nonportable-include-path
- cpp-options: -DVERSION="1.9"
+ cpp-options: -DVERSION="1.9.1"
build-depends:
Decimal
, Diff
@@ -97,7 +128,7 @@ library
, hashable >=1.2.4
, haskeline >=0.6
, here
- , hledger-lib >=1.9 && <2.0
+ , hledger-lib >=1.9.1 && <2.0
, lucid
, megaparsec >=5.0
, mtl
@@ -121,47 +152,16 @@ library
if (!(os(windows))) && (flag(terminfo))
build-depends:
terminfo
- exposed-modules:
- Hledger.Cli
- Hledger.Cli.Main
- Hledger.Cli.CliOptions
- Hledger.Cli.DocFiles
- Hledger.Cli.Utils
- Hledger.Cli.Version
- Hledger.Cli.Commands
- Hledger.Cli.Commands.Accounts
- Hledger.Cli.Commands.Activity
- Hledger.Cli.Commands.Add
- Hledger.Cli.Commands.Balance
- Hledger.Cli.Commands.Balancesheet
- Hledger.Cli.Commands.Balancesheetequity
- Hledger.Cli.Commands.Cashflow
- Hledger.Cli.Commands.Checkdates
- Hledger.Cli.Commands.Checkdupes
- Hledger.Cli.Commands.Close
- Hledger.Cli.Commands.Help
- Hledger.Cli.Commands.Import
- Hledger.Cli.Commands.Incomestatement
- Hledger.Cli.Commands.Prices
- Hledger.Cli.Commands.Print
- Hledger.Cli.Commands.Printunique
- Hledger.Cli.Commands.Register
- Hledger.Cli.Commands.Registermatch
- Hledger.Cli.Commands.Rewrite
- Hledger.Cli.Commands.Stats
- Hledger.Cli.Commands.Tags
- Hledger.Cli.CompoundBalanceCommand
- Text.Tabular.AsciiWide
- other-modules:
- Paths_hledger
default-language: Haskell2010
executable hledger
main-is: hledger-cli.hs
+ other-modules:
+ Paths_hledger
hs-source-dirs:
app
ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans -optP-Wno-nonportable-include-path
- cpp-options: -DVERSION="1.9"
+ cpp-options: -DVERSION="1.9.1"
build-depends:
Decimal
, HUnit
@@ -179,7 +179,7 @@ executable hledger
, haskeline >=0.6
, here
, hledger
- , hledger-lib >=1.9 && <2.0
+ , hledger-lib >=1.9.1 && <2.0
, mtl
, mtl-compat
, old-time
@@ -203,17 +203,17 @@ executable hledger
terminfo
if flag(threaded)
ghc-options: -threaded
- other-modules:
- Paths_hledger
default-language: Haskell2010
test-suite test
type: exitcode-stdio-1.0
main-is: test.hs
+ other-modules:
+ Paths_hledger
hs-source-dirs:
test
ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans -optP-Wno-nonportable-include-path
- cpp-options: -DVERSION="1.9"
+ cpp-options: -DVERSION="1.9.1"
build-depends:
Decimal
, HUnit
@@ -231,7 +231,7 @@ test-suite test
, haskeline >=0.6
, here
, hledger
- , hledger-lib >=1.9 && <2.0
+ , hledger-lib >=1.9.1 && <2.0
, mtl
, mtl-compat
, old-time
@@ -255,13 +255,13 @@ test-suite test
if (!(os(windows))) && (flag(terminfo))
build-depends:
terminfo
- other-modules:
- Paths_hledger
default-language: Haskell2010
benchmark bench
type: exitcode-stdio-1.0
main-is: bench.hs
+ other-modules:
+ Paths_hledger
hs-source-dirs:
bench
ghc-options: -Wall -fno-warn-unused-do-bind -fno-warn-name-shadowing -fno-warn-missing-signatures -fno-warn-type-defaults -fno-warn-orphans -optP-Wno-nonportable-include-path
@@ -275,7 +275,7 @@ benchmark bench
, filepath
, here
, hledger
- , hledger-lib >=1.9 && <2.0
+ , hledger-lib >=1.9.1 && <2.0
, html
, pretty-show >=1.6.4
, process
@@ -288,6 +288,4 @@ benchmark bench
if (!(os(windows))) && (flag(terminfo))
build-depends:
terminfo
- other-modules:
- Paths_hledger
default-language: Haskell2010
diff --git a/hledger.info b/hledger.info
index ee48104..4b7caaa 100644
--- a/hledger.info
+++ b/hledger.info
@@ -3,8 +3,8 @@ This is hledger.info, produced by makeinfo version 6.5 from stdin.

File: hledger.info, Node: Top, Next: EXAMPLES, Up: (dir)
-hledger(1) hledger 1.9
-**********************
+hledger(1) hledger 1.9.1
+************************
This is hledger's command-line interface (there are also curses and web
interfaces). Its basic function is to read a plain text file describing
@@ -785,13 +785,11 @@ instead most commands show transactions/postings/accounts which match
The following kinds of search terms can be used. Remember these can
also be prefixed with *'not:'*, eg to exclude a particular subaccount.
-*'REGEX'*
+*'REGEX', 'acct:REGEX'*
- match account names by this regular expression. (No prefix is
- equivalent to 'acct:').
-*'acct:REGEX'*
+ match account names by this regular expression. (With no prefix,
+ 'acct:' is assumed.) same as above
- same as above
*'amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N'*
match postings with a single-commodity amount that is equal to,
@@ -1138,8 +1136,46 @@ Show accounts and their balances. Aliases: b, bal.
with -budget, show unbudgeted accounts also
- The balance command displays accounts and balances. It is hledger's
-most featureful and versatile command.
+ The balance command is hledger's most versatile command. Note,
+despite the name, it is not always used for showing real-world account
+balances; the more accounting-aware balancesheet and incomestatement may
+be more convenient for that.
+
+ By default, it displays all accounts, and each account's change in
+balance during the entire period of the journal. Balance changes are
+calculated by adding up the postings in each account. You can limit the
+postings matched, by a query, to see fewer accounts, changes over a
+different time period, changes from only cleared transactions, etc.
+
+ If you include an account's complete history of postings in the
+report, the balance change is equivalent to the account's current ending
+balance. For a real-world account, typically you won't have all
+transactions in the journal; instead you'll have all transactions after
+a certain date, and an "opening balances" transaction setting the
+correct starting balance on that date. Then the balance command will
+show real-world account balances. In some cases the -H/-historical flag
+is used to ensure this (more below).
+
+ The balance command can produce several styles of report:
+* Menu:
+
+* Classic balance report::
+* Customising the classic balance report::
+* Colour support::
+* Flat mode::
+* Depth limited balance reports::
+* Multicolumn balance report::
+* Budget report::
+* Output format::
+
+
+File: hledger.info, Node: Classic balance report, Next: Customising the classic balance report, Up: balance
+
+4.4.1 Classic balance report
+----------------------------
+
+This is the original balance report, as found in Ledger. It usually
+looks like this:
$ hledger balance
$-1 assets
@@ -1155,11 +1191,6 @@ $ hledger balance
--------------------
0
- More precisely, the balance command shows the _change_ to each
-account's balance caused by all (matched) postings. In the common case
-where you do not filter by date and your journal sets the correct
-opening balances, this is the same as the account's ending balance.
-
By default, accounts are displayed hierarchically, with subaccounts
indented below their parent. At each level of the tree, accounts are
sorted by account code if any, then by account name. Or with
@@ -1167,7 +1198,7 @@ sorted by account code if any, then by account name. Or with
"Boring" accounts, which contain a single interesting subaccount and
no balance of their own, are elided into the following line for more
-compact output. (Not yet supported in tabular reports.) Use
+compact output. (Eg above, the "liabilities" account.) Use
'--no-elide' to prevent this.
Account balances are "inclusive" - they include the balances of any
@@ -1177,64 +1208,132 @@ subaccounts.
omitted. Use '-E/--empty' to show them.
A final total is displayed by default; use '-N/--no-total' to
-suppress it:
+suppress it, eg:
$ hledger balance -p 2008/6 expenses --no-total
$2 expenses
$1 food
$1 supplies
-* Menu:
+
+File: hledger.info, Node: Customising the classic balance report, Next: Colour support, Prev: Classic balance report, Up: balance
-* Flat mode::
-* Depth limited balance reports::
-* Multicolumn balance reports::
-* Budgets::
-* Custom balance output::
-* Colour support::
+4.4.2 Customising the classic balance report
+--------------------------------------------
+
+You can customise the layout of classic balance reports with '--format
+FMT':
+
+$ hledger balance --format "%20(account) %12(total)"
+ assets $-1
+ bank:saving $1
+ cash $-2
+ expenses $2
+ food $1
+ supplies $1
+ income $-2
+ gifts $-1
+ salary $-1
+ liabilities:debts $1
+---------------------------------
+ 0
+
+ The FMT format string (plus a newline) specifies the formatting
+applied to each account/balance pair. It may contain any suitable text,
+with data fields interpolated like so:
+
+ '%[MIN][.MAX](FIELDNAME)'
+
+ * MIN pads with spaces to at least this width (optional)
+ * MAX truncates at this width (optional)
+ * FIELDNAME must be enclosed in parentheses, and can be one of:
+
+ * 'depth_spacer' - a number of spaces equal to the account's
+ depth, or if MIN is specified, MIN * depth spaces.
+ * 'account' - the account's name
+ * 'total' - the account's balance/posted total, right justified
+
+ Also, FMT can begin with an optional prefix to control how
+multi-commodity amounts are rendered:
+
+ * '%_' - render on multiple lines, bottom-aligned (the default)
+ * '%^' - render on multiple lines, top-aligned
+ * '%,' - render on one line, comma-separated
+
+ There are some quirks. Eg in one-line mode, '%(depth_spacer)' has no
+effect, instead '%(account)' has indentation built in. Experimentation
+may be needed to get pleasing results.
+
+ Some example formats:
+
+ * '%(total)' - the account's total
+ * '%-20.20(account)' - the account's name, left justified, padded to
+ 20 characters and clipped at 20 characters
+ * '%,%-50(account) %25(total)' - account name padded to 50
+ characters, total padded to 20 characters, with multiple
+ commodities rendered on one line
+ * '%20(total) %2(depth_spacer)%-(account)' - the default format for
+ the single-column balance report
+
+
+File: hledger.info, Node: Colour support, Next: Flat mode, Prev: Customising the classic balance report, Up: balance
+
+4.4.3 Colour support
+--------------------
+
+The balance command shows negative amounts in red, if:
+
+ * the 'TERM' environment variable is not set to 'dumb'
+ * the output is not being redirected or piped anywhere

-File: hledger.info, Node: Flat mode, Next: Depth limited balance reports, Up: balance
+File: hledger.info, Node: Flat mode, Next: Depth limited balance reports, Prev: Colour support, Up: balance
-4.4.1 Flat mode
+4.4.4 Flat mode
---------------
-To see a flat list of full account names instead of the default
-hierarchical display, use '--flat'. In this mode, accounts (unless
-depth-clipped) show their "exclusive" balance, excluding any subaccount
-balances. In this mode, you can also use '--drop N' to omit the first
-few account name components.
+To see a flat list instead of the default hierarchical display, use
+'--flat'. In this mode, accounts (unless depth-clipped) show their full
+names and "exclusive" balance, excluding any subaccount balances. In
+this mode, you can also use '--drop N' to omit the first few account
+name components.
$ hledger balance -p 2008/6 expenses -N --flat --drop 1
$1 food
$1 supplies

-File: hledger.info, Node: Depth limited balance reports, Next: Multicolumn balance reports, Prev: Flat mode, Up: balance
+File: hledger.info, Node: Depth limited balance reports, Next: Multicolumn balance report, Prev: Flat mode, Up: balance
-4.4.2 Depth limited balance reports
+4.4.5 Depth limited balance reports
-----------------------------------
-With '--depth N', balance shows accounts only to the specified depth.
-This is very useful to show a complex charts of accounts in less detail.
-In flat mode, balances from accounts below the depth limit will be shown
-as part of a parent account at the depth limit.
+With '--depth N' or 'depth:N' or just '-N', balance reports show
+accounts only to the specified numeric depth. This is very useful to
+summarise a complex set of accounts and get an overview.
-$ hledger balance -N --depth 1
+$ hledger balance -N -1
$-1 assets
$2 expenses
$-2 income
$1 liabilities
+ Flat-mode balance reports, which normally show exclusive balances,
+show inclusive balances at the depth limit.
+

-File: hledger.info, Node: Multicolumn balance reports, Next: Budgets, Prev: Depth limited balance reports, Up: balance
+File: hledger.info, Node: Multicolumn balance report, Next: Budget report, Prev: Depth limited balance reports, Up: balance
-4.4.3 Multicolumn balance reports
----------------------------------
+4.4.6 Multicolumn balance report
+--------------------------------
+
+Multicolumn or tabular balance reports are a very useful hledger
+feature, and usually the preferred style. They share many of the above
+features, but they show the report as a table, with columns representing
+time periods. This mode is activated by providing a reporting interval.
-With a reporting interval, multiple balance columns will be shown, one
-for each report period. There are three types of multi-column balance
-report, showing different information:
+ There are three types of multicolumn balance report, showing
+different information:
1. By default: each column shows the sum of postings in that period,
ie the account's change of balance in that period. This is useful
@@ -1286,8 +1385,8 @@ report, showing different information:
----------------------++-------------------------------------
|| 0 0 0
- Multi-column balance reports display accounts in flat mode by
-default; to see the hierarchy, use '--tree'.
+ Multicolumn balance reports display accounts in flat mode by default;
+to see the hierarchy, use '--tree'.
With a reporting interval (like '--quarterly' above), the report
start/end dates will be adjusted if necessary so that they encompass the
@@ -1326,17 +1425,26 @@ Balance changes in 2008:
# Average is rounded to the dollar here since all journal amounts are
+ Limitations:
+
+ In multicolumn reports the '-V/--value' flag uses the market price on
+the report end date, for all columns (not the price on each column's end
+date).
+
+ Eliding of boring parent accounts in tree mode, as in the classic
+balance report, is not yet supported in multicolumn reports.
+

-File: hledger.info, Node: Budgets, Next: Custom balance output, Prev: Multicolumn balance reports, Up: balance
+File: hledger.info, Node: Budget report, Next: , Prev: Multicolumn balance report, Up: balance
-4.4.4 Budgets
--------------
+4.4.7 Budget report
+-------------------
-With '--budget' and a report interval, all periodic transactions in your
-journal with that interval, active during the requested report period,
-are interpreted as recurring budget goals for the specified accounts
-(and subaccounts), and the report will show the difference between
-actual and budgeted balances.
+With '--budget', extra columns are displayed showing budget goals for
+each account and period, if any. Budget goals are defined by periodic
+transactions. This is very useful for comparing planned and actual
+income, expenses, time usage, etc. -budget is most often combined with
+a report interval.
For example, you can take average monthly expenses in the common
expense categories to construct a minimal monthly budget:
@@ -1365,138 +1473,55 @@ expense categories to construct a minimal monthly budget:
expenses:gifts $100
assets:bank:checking
- You can now see a monthly budget performance report:
+ You can now see a monthly budget report:
$ hledger balance -M --budget
-Balance changes in 2017/11/01-2017/12/31:
-
- || 2017/11 2017/12
-=======================++=================================================
- <unbudgeted>:expenses || $20 $100
- assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
- expenses:bus || $49 [98% of $50] $53 [106% of $50]
- expenses:food || $396 [99% of $400] $412 [103% of $400]
- expenses:movies || $30 [100% of $30] 0 [0% of $30]
- income || $1950 [98% of $2000] $2100 [105% of $2000]
------------------------++-------------------------------------------------
- || 0 0
-
- You can roll over unspent budgets to next period with '--cumulative':
-
-$ hledger balance -M --budget --cumulative
-Ending balances (cumulative) in 2017/11/01-2017/12/31:
-
- || 2017/11/30 2017/12/31
-=======================++=================================================
- <unbudgeted>:expenses || $20 $120
- assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960]
- expenses:bus || $49 [98% of $50] $102 [102% of $100]
- expenses:food || $396 [99% of $400] $808 [101% of $800]
- expenses:movies || $30 [100% of $30] $30 [50% of $60]
- income || $1950 [98% of $2000] $4050 [101% of $4000]
------------------------++-------------------------------------------------
- || 0 0
-
- Accounts with no budget goals (not mentioned in the periodic
-transactions) will be aggregated under '<unbudgeted>', unless you add
-the '--show-unbudgeted' flag to display them normally:
-
-$ hledger balance --budget --show-unbudgeted
-Balance changes in 2017/11/01-2017/12/31:
+Budget performance in 2017/11/01-2017/12/31:
|| 2017/11 2017/12
======================++=================================================
+ <unbudgeted> || $20 $100
assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
expenses:bus || $49 [98% of $50] $53 [106% of $50]
expenses:food || $396 [99% of $400] $412 [103% of $400]
- expenses:gifts || 0 $100
expenses:movies || $30 [100% of $30] 0 [0% of $30]
- expenses:supplies || $20 0
income || $1950 [98% of $2000] $2100 [105% of $2000]
----------------------++-------------------------------------------------
|| 0 0
- Note -budget first arrived in hledger in 1.5 and is still pretty
-young; join the discussions on mail list and issue tracker to help us
-refine it.
-
- For more examples, see Budgeting and Forecasting.
-
-
-File: hledger.info, Node: Custom balance output, Next: Colour support, Prev: Budgets, Up: balance
-
-4.4.5 Custom balance output
----------------------------
-
-You can customise the layout of simple (non-tabular) balance reports
-with '--format FMT':
-
-$ hledger balance --format "%20(account) %12(total)"
- assets $-1
- bank:saving $1
- cash $-2
- expenses $2
- food $1
- supplies $1
- income $-2
- gifts $-1
- salary $-1
- liabilities:debts $1
----------------------------------
- 0
-
- The FMT format string (plus a newline) specifies the formatting
-applied to each account/balance pair. It may contain any suitable text,
-with data fields interpolated like so:
-
- '%[MIN][.MAX](FIELDNAME)'
-
- * MIN pads with spaces to at least this width (optional)
- * MAX truncates at this width (optional)
- * FIELDNAME must be enclosed in parentheses, and can be one of:
+ By default, only accounts with budget goals during the report period
+are shown. '--show-unbudgeted' shows unbudgeted accounts as well.
+Top-level accounts with no budget goals anywhere below them are grouped
+under '<unbudgeted>'.
- * '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
+ You can roll over unspent budgets to next period with '--cumulative':
- Also, FMT can begin with an optional prefix to control how
-multi-commodity amounts are rendered:
+$ hledger balance -M --budget --cumulative
+Budget performance in 2017/11/01-2017/12/31:
- * '%_' - render on multiple lines, bottom-aligned (the default)
- * '%^' - render on multiple lines, top-aligned
- * '%,' - render on one line, comma-separated
+ || 2017/11/30 2017/12/31
+======================++=================================================
+ <unbudgeted> || $20 $120
+ assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960]
+ expenses:bus || $49 [98% of $50] $102 [102% of $100]
+ expenses:food || $396 [99% of $400] $808 [101% of $800]
+ expenses:movies || $30 [100% of $30] $30 [50% of $60]
+ income || $1950 [98% of $2000] $4050 [101% of $4000]
+----------------------++-------------------------------------------------
+ || 0 0
- 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.
+ Note, the '-S/--sort-amount' flag is not yet fully supported with
+'--budget'.
- Some example formats:
+ For more examples, see Budgeting and Forecasting.
- * '%(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
+4.4.8 Output format
+-------------------
- This command also supports output destination and output format
+The balance command supports output destination and output format
selection.

-File: hledger.info, Node: Colour support, Prev: Custom balance output, Up: balance
-
-4.4.6 Colour support
---------------------
-
-The balance command shows negative amounts in red, if:
-
- * the 'TERM' environment variable is not set to 'dumb'
- * the output is not being redirected or piped anywhere
-
-
File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: COMMANDS
4.5 balancesheet
@@ -2393,135 +2418,138 @@ hledger-check.hs checks more powerful account balance assertions.

Tag Table:
Node: Top68
-Node: EXAMPLES1882
-Ref: #examples1982
-Node: OPTIONS3628
-Ref: #options3730
-Node: General options4095
-Ref: #general-options4220
-Node: Command options6819
-Ref: #command-options6970
-Node: Command arguments7368
-Ref: #command-arguments7522
-Node: Argument files7643
-Ref: #argument-files7794
-Node: Special characters8060
-Ref: #special-characters8213
-Node: Input files9632
-Ref: #input-files9768
-Node: Smart dates11738
-Ref: #smart-dates11879
-Node: Report start & end date12858
-Ref: #report-start-end-date13028
-Node: Report intervals14093
-Ref: #report-intervals14256
-Node: Period expressions14657
-Ref: #period-expressions14817
-Node: Depth limiting18774
-Ref: #depth-limiting18918
-Node: Pivoting19260
-Ref: #pivoting19378
-Node: Cost21054
-Ref: #cost21162
-Node: Market value21280
-Ref: #market-value21415
-Node: Combining -B and -V22598
-Ref: #combining--b-and--v22761
-Node: Output destination22908
-Ref: #output-destination23070
-Node: Output format23353
-Ref: #output-format23505
-Node: Regular expressions23890
-Ref: #regular-expressions24027
-Node: QUERIES25388
-Ref: #queries25490
-Node: COMMANDS29457
-Ref: #commands29569
-Node: accounts30551
-Ref: #accounts30649
-Node: activity31895
-Ref: #activity32005
-Node: add32365
-Ref: #add32464
-Node: balance35125
-Ref: #balance35236
-Node: Flat mode38740
-Ref: #flat-mode38865
-Node: Depth limited balance reports39285
-Ref: #depth-limited-balance-reports39486
-Node: Multicolumn balance reports39906
-Ref: #multicolumn-balance-reports40101
-Node: Budgets44790
-Ref: #budgets44937
-Node: Custom balance output48906
-Ref: #custom-balance-output49068
-Node: Colour support51234
-Ref: #colour-support51366
-Node: balancesheet51539
-Ref: #balancesheet51675
-Node: balancesheetequity53986
-Ref: #balancesheetequity54135
-Node: cashflow54672
-Ref: #cashflow54800
-Node: check-dates56923
-Ref: #check-dates57050
-Node: check-dupes57167
-Ref: #check-dupes57291
-Node: close57428
-Ref: #close57535
-Node: help57865
-Ref: #help57965
-Node: import59039
-Ref: #import59153
-Node: incomestatement59883
-Ref: #incomestatement60017
-Node: prices62421
-Ref: #prices62536
-Node: print62579
-Ref: #print62689
-Node: print-unique67583
-Ref: #print-unique67709
-Node: register67777
-Ref: #register67904
-Node: Custom register output72405
-Ref: #custom-register-output72534
-Node: register-match73764
-Ref: #register-match73898
-Node: rewrite74081
-Ref: #rewrite74198
-Node: stats74267
-Ref: #stats74370
-Node: tags75240
-Ref: #tags75338
-Node: test75574
-Ref: #test75658
-Node: ADD-ON COMMANDS76026
-Ref: #add-on-commands76136
-Node: Official add-ons77423
-Ref: #official-add-ons77563
-Node: api77650
-Ref: #api77739
-Node: ui77791
-Ref: #ui77890
-Node: web77948
-Ref: #web78037
-Node: Third party add-ons78083
-Ref: #third-party-add-ons78258
-Node: diff78393
-Ref: #diff78490
-Node: iadd78589
-Ref: #iadd78703
-Node: interest78786
-Ref: #interest78907
-Node: irr79002
-Ref: #irr79100
-Node: Experimental add-ons79178
-Ref: #experimental-add-ons79330
-Node: autosync79610
-Ref: #autosync79721
-Node: chart79960
-Ref: #chart80079
-Node: check80150
-Ref: #check80252
+Node: EXAMPLES1886
+Ref: #examples1986
+Node: OPTIONS3632
+Ref: #options3734
+Node: General options4099
+Ref: #general-options4224
+Node: Command options6823
+Ref: #command-options6974
+Node: Command arguments7372
+Ref: #command-arguments7526
+Node: Argument files7647
+Ref: #argument-files7798
+Node: Special characters8064
+Ref: #special-characters8217
+Node: Input files9636
+Ref: #input-files9772
+Node: Smart dates11742
+Ref: #smart-dates11883
+Node: Report start & end date12862
+Ref: #report-start-end-date13032
+Node: Report intervals14097
+Ref: #report-intervals14260
+Node: Period expressions14661
+Ref: #period-expressions14821
+Node: Depth limiting18778
+Ref: #depth-limiting18922
+Node: Pivoting19264
+Ref: #pivoting19382
+Node: Cost21058
+Ref: #cost21166
+Node: Market value21284
+Ref: #market-value21419
+Node: Combining -B and -V22602
+Ref: #combining--b-and--v22765
+Node: Output destination22912
+Ref: #output-destination23074
+Node: Output format23357
+Ref: #output-format23509
+Node: Regular expressions23894
+Ref: #regular-expressions24031
+Node: QUERIES25392
+Ref: #queries25494
+Node: COMMANDS29456
+Ref: #commands29568
+Node: accounts30550
+Ref: #accounts30648
+Node: activity31894
+Ref: #activity32004
+Node: add32364
+Ref: #add32463
+Node: balance35124
+Ref: #balance35235
+Node: Classic balance report38318
+Ref: #classic-balance-report38491
+Node: Customising the classic balance report39860
+Ref: #customising-the-classic-balance-report40088
+Node: Colour support42162
+Ref: #colour-support42329
+Node: Flat mode42502
+Ref: #flat-mode42650
+Node: Depth limited balance reports43063
+Ref: #depth-limited-balance-reports43263
+Node: Multicolumn balance report43719
+Ref: #multicolumn-balance-report43917
+Node: Budget report49097
+Ref: #budget-report49240
+Ref: #output-format-152274
+Node: balancesheet52352
+Ref: #balancesheet52488
+Node: balancesheetequity54799
+Ref: #balancesheetequity54948
+Node: cashflow55485
+Ref: #cashflow55613
+Node: check-dates57736
+Ref: #check-dates57863
+Node: check-dupes57980
+Ref: #check-dupes58104
+Node: close58241
+Ref: #close58348
+Node: help58678
+Ref: #help58778
+Node: import59852
+Ref: #import59966
+Node: incomestatement60696
+Ref: #incomestatement60830
+Node: prices63234
+Ref: #prices63349
+Node: print63392
+Ref: #print63502
+Node: print-unique68396
+Ref: #print-unique68522
+Node: register68590
+Ref: #register68717
+Node: Custom register output73218
+Ref: #custom-register-output73347
+Node: register-match74577
+Ref: #register-match74711
+Node: rewrite74894
+Ref: #rewrite75011
+Node: stats75080
+Ref: #stats75183
+Node: tags76053
+Ref: #tags76151
+Node: test76387
+Ref: #test76471
+Node: ADD-ON COMMANDS76839
+Ref: #add-on-commands76949
+Node: Official add-ons78236
+Ref: #official-add-ons78376
+Node: api78463
+Ref: #api78552
+Node: ui78604
+Ref: #ui78703
+Node: web78761
+Ref: #web78850
+Node: Third party add-ons78896
+Ref: #third-party-add-ons79071
+Node: diff79206
+Ref: #diff79303
+Node: iadd79402
+Ref: #iadd79516
+Node: interest79599
+Ref: #interest79720
+Node: irr79815
+Ref: #irr79913
+Node: Experimental add-ons79991
+Ref: #experimental-add-ons80143
+Node: autosync80423
+Ref: #autosync80534
+Node: chart80773
+Ref: #chart80892
+Node: check80963
+Ref: #check81065

End Tag Table
diff --git a/hledger.txt b/hledger.txt
index eaa7c5a..c179ae3 100644
--- a/hledger.txt
+++ b/hledger.txt
@@ -728,11 +728,10 @@ QUERIES
The following kinds of search terms can be used. Remember these can
also be prefixed with not:, eg to exclude a particular subaccount.
- REGEX match account names by this regular expression. (No prefix is
- equivalent to acct:).
-
- acct:REGEX
- same as above
+ REGEX, acct:REGEX
+ match account names by this regular expression. (With no pre-
+ fix, acct: is assumed.)
+ same as above
amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N
match postings with a single-commodity amount that is equal to,
@@ -1028,8 +1027,31 @@ COMMANDS
--show-unbudgeted
with -budget, show unbudgeted accounts also
- The balance command displays accounts and balances. It is hledger's
- most featureful and versatile command.
+ The balance command is hledger's most versatile command. Note, despite
+ the name, it is not always used for showing real-world account bal-
+ ances; the more accounting-aware balancesheet and incomestatement may
+ be more convenient for that.
+
+ By default, it displays all accounts, and each account's change in bal-
+ ance during the entire period of the journal. Balance changes are cal-
+ culated by adding up the postings in each account. You can limit the
+ postings matched, by a query, to see fewer accounts, changes over a
+ different time period, changes from only cleared transactions, etc.
+
+ If you include an account's complete history of postings in the report,
+ the balance change is equivalent to the account's current ending bal-
+ ance. For a real-world account, typically you won't have all transac-
+ tions in the journal; instead you'll have all transactions after a cer-
+ tain date, and an "opening balances" transaction setting the correct
+ starting balance on that date. Then the balance command will show
+ real-world account balances. In some cases the -H/-historical flag is
+ used to ensure this (more below).
+
+ The balance command can produce several styles of report:
+
+ Classic balance report
+ This is the original balance report, as found in Ledger. It usually
+ looks like this:
$ hledger balance
$-1 assets
@@ -1045,62 +1067,135 @@ COMMANDS
--------------------
0
- More precisely, the balance command shows the change to each account's
- balance caused by all (matched) postings. In the common case where you
- do not filter by date and your journal sets the correct opening bal-
- ances, this is the same as the account's ending balance.
-
- By default, accounts are displayed hierarchically, with subaccounts
- indented below their parent. At each level of the tree, accounts are
- sorted by account code if any, then by account name. Or with
+ By default, accounts are displayed hierarchically, with subaccounts
+ indented below their parent. At each level of the tree, accounts are
+ sorted by account code if any, then by account name. Or with
-S/--sort-amount, by their balance amount.
"Boring" accounts, which contain a single interesting subaccount and no
- balance of their own, are elided into the following line for more com-
- pact output. (Not yet supported in tabular reports.) Use --no-elide to
+ balance of their own, are elided into the following line for more com-
+ pact output. (Eg above, the "liabilities" account.) Use --no-elide to
prevent this.
- Account balances are "inclusive" - they include the balances of any
+ Account balances are "inclusive" - they include the balances of any
subaccounts.
- Accounts which have zero balance (and no non-zero subaccounts) are
+ Accounts which have zero balance (and no non-zero subaccounts) are
omitted. Use -E/--empty to show them.
- A final total is displayed by default; use -N/--no-total to suppress
- it:
+ A final total is displayed by default; use -N/--no-total to suppress
+ it, eg:
$ hledger balance -p 2008/6 expenses --no-total
$2 expenses
$1 food
$1 supplies
+ Customising the classic balance report
+ You can customise the layout of classic balance reports with --for-
+ mat FMT:
+
+ $ hledger balance --format "%20(account) %12(total)"
+ assets $-1
+ bank:saving $1
+ cash $-2
+ expenses $2
+ food $1
+ supplies $1
+ income $-2
+ gifts $-1
+ salary $-1
+ liabilities:debts $1
+ ---------------------------------
+ 0
+
+ The FMT format string (plus a newline) specifies the formatting applied
+ to each account/balance pair. It may contain any suitable text, with
+ data fields interpolated like so:
+
+ %[MIN][.MAX](FIELDNAME)
+
+ 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
+ effect, 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
+
+ Colour support
+ The balance command shows negative amounts in red, if:
+
+ o the TERM environment variable is not set to dumb
+
+ o the output is not being redirected or piped anywhere
+
Flat mode
- To see a flat list of full account names instead of the default hierar-
- chical display, use --flat. In this mode, accounts (unless
- depth-clipped) show their "exclusive" balance, excluding any subaccount
- balances. In this mode, you can also use --drop N to omit the first
- few account name components.
+ To see a flat list instead of the default hierarchical display, use
+ --flat. In this mode, accounts (unless depth-clipped) show their full
+ names and "exclusive" balance, excluding any subaccount balances. In
+ this mode, you can also use --drop N to omit the first few account name
+ components.
$ hledger balance -p 2008/6 expenses -N --flat --drop 1
$1 food
$1 supplies
Depth limited balance reports
- With --depth N, balance shows accounts only to the specified depth.
- This is very useful to show a complex charts of accounts in less
- detail. In flat mode, balances from accounts below the depth limit
- will be shown as part of a parent account at the depth limit.
+ With --depth N or depth:N or just -N, balance reports show accounts
+ only to the specified numeric depth. This is very useful to summarise
+ a complex set of accounts and get an overview.
- $ hledger balance -N --depth 1
+ $ hledger balance -N -1
$-1 assets
$2 expenses
$-2 income
$1 liabilities
- Multicolumn balance reports
- With a reporting interval, multiple balance columns will be shown, one
- for each report period. There are three types of multi-column balance
- report, showing different information:
+ Flat-mode balance reports, which normally show exclusive balances, show
+ inclusive balances at the depth limit.
+
+ Multicolumn balance report
+ Multicolumn or tabular balance reports are a very useful hledger fea-
+ ture, and usually the preferred style. They share many of the above
+ features, but they show the report as a table, with columns represent-
+ ing time periods. This mode is activated by providing a reporting
+ interval.
+
+ There are three types of multicolumn balance report, showing different
+ information:
1. By default: each column shows the sum of postings in that period, ie
the account's change of balance in that period. This is useful eg
@@ -1152,7 +1247,7 @@ COMMANDS
----------------------++-------------------------------------
|| 0 0 0
- Multi-column balance reports display accounts in flat mode by default;
+ Multicolumn balance reports display accounts in flat mode by default;
to see the hierarchy, use --tree.
With a reporting interval (like --quarterly above), the report
@@ -1192,14 +1287,23 @@ COMMANDS
# Average is rounded to the dollar here since all journal amounts are
- Budgets
- With --budget and a report interval, all periodic transactions in your
- journal with that interval, active during the requested report period,
- are interpreted as recurring budget goals for the specified accounts
- (and subaccounts), and the report will show the difference between
- actual and budgeted balances.
+ Limitations:
+
+ In multicolumn reports the -V/--value flag uses the market price on the
+ report end date, for all columns (not the price on each column's end
+ date).
+
+ Eliding of boring parent accounts in tree mode, as in the classic bal-
+ ance report, is not yet supported in multicolumn reports.
- For example, you can take average monthly expenses in the common
+ Budget report
+ With --budget, extra columns are displayed showing budget goals for
+ each account and period, if any. Budget goals are defined by periodic
+ transactions. This is very useful for comparing planned and actual
+ income, expenses, time usage, etc. -budget is most often combined with
+ a report interval.
+
+ For example, you can take average monthly expenses in the common
expense categories to construct a minimal monthly budget:
;; Budget
@@ -1226,144 +1330,59 @@ COMMANDS
expenses:gifts $100
assets:bank:checking
- You can now see a monthly budget performance report:
+ You can now see a monthly budget report:
$ hledger balance -M --budget
- Balance changes in 2017/11/01-2017/12/31:
-
- || 2017/11 2017/12
- =======================++=================================================
- <unbudgeted>:expenses || $20 $100
- assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
- expenses:bus || $49 [98% of $50] $53 [106% of $50]
- expenses:food || $396 [99% of $400] $412 [103% of $400]
- expenses:movies || $30 [100% of $30] 0 [0% of $30]
- income || $1950 [98% of $2000] $2100 [105% of $2000]
- -----------------------++-------------------------------------------------
- || 0 0
-
- You can roll over unspent budgets to next period with --cumulative:
-
- $ hledger balance -M --budget --cumulative
- Ending balances (cumulative) in 2017/11/01-2017/12/31:
-
- || 2017/11/30 2017/12/31
- =======================++=================================================
- <unbudgeted>:expenses || $20 $120
- assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960]
- expenses:bus || $49 [98% of $50] $102 [102% of $100]
- expenses:food || $396 [99% of $400] $808 [101% of $800]
- expenses:movies || $30 [100% of $30] $30 [50% of $60]
- income || $1950 [98% of $2000] $4050 [101% of $4000]
- -----------------------++-------------------------------------------------
- || 0 0
-
- Accounts with no budget goals (not mentioned in the periodic transac-
- tions) will be aggregated under <unbudgeted>, unless you add the
- --show-unbudgeted flag to display them normally:
-
- $ hledger balance --budget --show-unbudgeted
- Balance changes in 2017/11/01-2017/12/31:
+ Budget performance in 2017/11/01-2017/12/31:
|| 2017/11 2017/12
======================++=================================================
+ <unbudgeted> || $20 $100
assets:bank:checking || $-2445 [99% of $-2480] $-2665 [107% of $-2480]
expenses:bus || $49 [98% of $50] $53 [106% of $50]
expenses:food || $396 [99% of $400] $412 [103% of $400]
- expenses:gifts || 0 $100
expenses:movies || $30 [100% of $30] 0 [0% of $30]
- expenses:supplies || $20 0
income || $1950 [98% of $2000] $2100 [105% of $2000]
----------------------++-------------------------------------------------
|| 0 0
- Note -budget first arrived in hledger in 1.5 and is still pretty young;
- join the discussions on mail list and issue tracker to help us refine
- it.
-
- For more examples, see Budgeting and Forecasting.
-
- Custom balance output
- You can customise the layout of simple (non-tabular) balance reports
- with --format FMT:
+ By default, only accounts with budget goals during the report period
+ are shown. --show-unbudgeted shows unbudgeted accounts as well.
+ Top-level accounts with no budget goals anywhere below them are grouped
+ under <unbudgeted>.
- $ hledger balance --format "%20(account) %12(total)"
- assets $-1
- bank:saving $1
- cash $-2
- expenses $2
- food $1
- supplies $1
- income $-2
- gifts $-1
- salary $-1
- liabilities:debts $1
- ---------------------------------
- 0
-
- The FMT format string (plus a newline) specifies the formatting applied
- to each account/balance pair. It may contain any suitable text, with
- data fields interpolated like so:
-
- %[MIN][.MAX](FIELDNAME)
-
- 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
- effect, 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
+ You can roll over unspent budgets to next period with --cumulative:
- o %20(total) %2(depth_spacer)%-(account) - the default format for the
- single-column balance report
+ $ hledger balance -M --budget --cumulative
+ Budget performance in 2017/11/01-2017/12/31:
- This command also supports output destination and output format selec-
- tion.
+ || 2017/11/30 2017/12/31
+ ======================++=================================================
+ <unbudgeted> || $20 $120
+ assets:bank:checking || $-2445 [99% of $-2480] $-5110 [103% of $-4960]
+ expenses:bus || $49 [98% of $50] $102 [102% of $100]
+ expenses:food || $396 [99% of $400] $808 [101% of $800]
+ expenses:movies || $30 [100% of $30] $30 [50% of $60]
+ income || $1950 [98% of $2000] $4050 [101% of $4000]
+ ----------------------++-------------------------------------------------
+ || 0 0
- Colour support
- The balance command shows negative amounts in red, if:
+ Note, the -S/--sort-amount flag is not yet fully supported with --bud-
+ get.
- o the TERM environment variable is not set to dumb
+ For more examples, see Budgeting and Forecasting.
- o the output is not being redirected or piped anywhere
+ Output format
+ The balance command supports output destination and output format
+ selection.
balancesheet
This command displays a simple balance sheet, showing historical ending
- balances of asset and liability accounts (ignoring any report begin
- date). It assumes that these accounts are under a top-level asset or
- liability account (case insensitive, plural forms also allowed). Note
- this report shows all account balances with normal positive sign (like
- conventional financial statements, unlike balance/print/register)
+ balances of asset and liability accounts (ignoring any report begin
+ date). It assumes that these accounts are under a top-level asset or
+ liability account (case insensitive, plural forms also allowed). Note
+ this report shows all account balances with normal positive sign (like
+ conventional financial statements, unlike balance/print/register)
(experimental). (bs)
--change
@@ -1371,7 +1390,7 @@ COMMANDS
balances
--cumulative
- show balance change accumulated across periods (in multicolumn
+ show balance change accumulated across periods (in multicolumn
reports), instead of historical ending balances
-H --historical
@@ -1427,16 +1446,16 @@ COMMANDS
0
With a reporting interval, multiple columns will be shown, one for each
- report period. As with multicolumn balance reports, you can alter the
- report mode with --change/--cumulative/--historical. Normally bal-
- ancesheet shows historical ending balances, which is what you need for
+ report period. As with multicolumn balance reports, you can alter the
+ report mode with --change/--cumulative/--historical. Normally bal-
+ ancesheet shows historical ending balances, which is what you need for
a balance sheet; note this means it ignores report begin dates.
- This command also supports output destination and output format selec-
+ This command also supports output destination and output format selec-
tion.
balancesheetequity
- Just like balancesheet, but also reports Equity (which it assumes is
+ Just like balancesheet, but also reports Equity (which it assumes is
under a top-level equity account).
Example:
@@ -1466,10 +1485,10 @@ COMMANDS
0
cashflow
- This command displays a simple cashflow statement, showing changes in
- "cash" accounts. It assumes that these accounts are under a top-level
- asset account (case insensitive, plural forms also allowed) and do not
- contain receivable or A/R in their name. Note this report shows all
+ This command displays a simple cashflow statement, showing changes in
+ "cash" accounts. It assumes that these accounts are under a top-level
+ asset account (case insensitive, plural forms also allowed) and do not
+ contain receivable or A/R in their name. Note this report shows all
account balances with normal positive sign (like conventional financial
statements, unlike balance/print/register) (experimental). (cf)
@@ -1477,7 +1496,7 @@ COMMANDS
show balance change in each period (default)
--cumulative
- show balance change accumulated across periods (in multicolumn
+ show balance change accumulated across periods (in multicolumn
reports), instead of changes during periods
-H --historical
@@ -1528,38 +1547,38 @@ COMMANDS
$-1
With a reporting interval, multiple columns will be shown, one for each
- report period. Normally cashflow shows changes in assets per period,
- though as with multicolumn balance reports you can alter the report
+ report period. Normally cashflow shows changes in assets per period,
+ though as with multicolumn balance reports you can alter the report
mode with --change/--cumulative/--historical.
- This command also supports output destination and output format selec-
+ This command also supports output destination and output format selec-
tion.
check-dates
- Check that transactions are sorted by increasing date. With a query,
+ Check that transactions are sorted by increasing date. With a query,
only matched transactions' dates are checked.
check-dupes
- Report account names having the same leaf but different prefixes. An
+ Report account names having the same leaf but different prefixes. An
example: http://stefanorodighiero.net/software/hledger-dupes.html
close
- Print closing/opening transactions that bring some or all account bal-
- ances to zero and back. Can be useful for bringing asset/liability
+ Print closing/opening transactions that bring some or all account bal-
+ ances to zero and back. Can be useful for bringing asset/liability
balances across file boundaries, or for closing out income/expenses for
- a period. This was formerly called "equity", as in Ledger, and that
+ a period. This was formerly called "equity", as in Ledger, and that
alias is also accepted. See close -help for more.
help
Show any of the hledger manuals.
- The help command displays any of the main hledger manuals, in one of
- several ways. Run it with no argument to list the manuals, or provide
+ The help command displays any of the main hledger manuals, in one of
+ several ways. Run it with no argument to list the manuals, or provide
a full or partial manual name to select one.
- hledger manuals are available in several formats. hledger help will
- use the first of these display methods that it finds: info, man,
- $PAGER, less, stdout (or when non-interactive, just stdout). You can
+ hledger manuals are available in several formats. hledger help will
+ use the first of these display methods that it finds: info, man,
+ $PAGER, less, stdout (or when non-interactive, just stdout). You can
force a particular viewer with the --info, --man, --pager, --cat flags.
$ hledger help
@@ -1583,7 +1602,7 @@ COMMANDS
...
import
- Read new transactions added to each FILE since last run, and add them
+ Read new transactions added to each FILE since last run, and add them
to the main journal file.
--dry-run
@@ -1593,28 +1612,28 @@ COMMANDS
each one. So eg to add new transactions from all CSV files to the main
journal, it's just: hledger import *.csv
- New transactions are detected in the same way as print -new: by assum-
+ New transactions are detected in the same way as print -new: by assum-
ing transactions are always added to the input files in increasing date
order, and by saving .latest.FILE state files.
- The -dry-run output is in journal format, so you can filter it, eg to
+ The -dry-run output is in journal format, so you can filter it, eg to
see only uncategorised transactions:
$ hledger import --dry ... | hledger -f- print unknown --ignore-assertions
incomestatement
- This command displays a simple income statement, showing revenues and
- expenses during a period. It assumes that these accounts are under a
- top-level revenue or income or expense account (case insensitive, plu-
- ral forms also allowed). Note this report shows all account balances
- with normal positive sign (like conventional financial statements,
+ This command displays a simple income statement, showing revenues and
+ expenses during a period. It assumes that these accounts are under a
+ top-level revenue or income or expense account (case insensitive, plu-
+ ral forms also allowed). Note this report shows all account balances
+ with normal positive sign (like conventional financial statements,
unlike balance/print/register) (experimental). (is)
--change
show balance change in each period (default)
--cumulative
- show balance change accumulated across periods (in multicolumn
+ show balance change accumulated across periods (in multicolumn
reports), instead of changes during periods
-H --historical
@@ -1648,8 +1667,8 @@ COMMANDS
--sort-amount
sort by amount instead of account code/name
- This command displays a simple income statement. It currently assumes
- that you have top-level accounts named income (or revenue) and expense
+ This command displays a simple income statement. It currently assumes
+ that you have top-level accounts named income (or revenue) and expense
(plural forms also allowed.)
$ hledger incomestatement
@@ -1674,11 +1693,11 @@ COMMANDS
0
With a reporting interval, multiple columns will be shown, one for each
- report period. Normally incomestatement shows revenues/expenses per
- period, though as with multicolumn balance reports you can alter the
+ report period. Normally incomestatement shows revenues/expenses per
+ period, though as with multicolumn balance reports you can alter the
report mode with --change/--cumulative/--historical.
- This command also supports output destination and output format selec-
+ This command also supports output destination and output format selec-
tion.
prices
@@ -1688,7 +1707,7 @@ COMMANDS
Show transactions from the journal. Aliases: p, txns.
-m STR --match=STR
- show the transaction whose description is most similar to STR,
+ show the transaction whose description is most similar to STR,
and is most recent
--new show only newer-dated transactions added in each file since last
@@ -1701,7 +1720,7 @@ COMMANDS
select the output format. Supported formats: txt, csv.
-o FILE --output-file=FILE
- write output to FILE. A file extension matching one of the
+ write output to FILE. A file extension matching one of the
above formats selects that format.
$ hledger print
@@ -1732,39 +1751,39 @@ COMMANDS
it does not preserve directives or inter-transaction comments
Normally, the journal entry's explicit or implicit amount style is pre-
- served. Ie when an amount is omitted in the journal, it will be omit-
- ted in the output. You can use the -x/--explicit flag to make all
+ served. Ie when an amount is omitted in the journal, it will be omit-
+ ted in the output. You can use the -x/--explicit flag to make all
amounts explicit, which can be useful for troubleshooting or for making
your journal more readable and robust against data entry errors. Note,
- -x will cause postings with a multi-commodity amount (these can arise
- when a multi-commodity transaction has an implicit amount) will be
- split into multiple single-commodity postings, for valid journal out-
+ -x will cause postings with a multi-commodity amount (these can arise
+ when a multi-commodity transaction has an implicit amount) will be
+ split into multiple single-commodity postings, for valid journal out-
put.
- With -B/--cost, amounts with transaction prices are converted to cost
+ With -B/--cost, amounts with transaction prices are converted to cost
using that price. This can be used for troubleshooting.
- With -m/--match and a STR argument, print will show at most one trans-
- action: the one one whose description is most similar to STR, and is
- most recent. STR should contain at least two characters. If there is
+ With -m/--match and a STR argument, print will show at most one trans-
+ action: the one one whose description is most similar to STR, and is
+ most recent. STR should contain at least two characters. If there is
no similar-enough match, no transaction will be shown.
With --new, for each FILE being read, hledger reads (and writes) a spe-
- cial state file (.latest.FILE in the same directory), containing the
- latest transaction date(s) that were seen last time FILE was read.
- When this file is found, only transactions with newer dates (and new
- transactions on the latest date) are printed. This is useful for
- ignoring already-seen entries in import data, such as downloaded CSV
+ cial state file (.latest.FILE in the same directory), containing the
+ latest transaction date(s) that were seen last time FILE was read.
+ When this file is found, only transactions with newer dates (and new
+ transactions on the latest date) are printed. This is useful for
+ ignoring already-seen entries in import data, such as downloaded CSV
files. Eg:
$ hledger -f bank1.csv print --new
# shows transactions added since last print --new on this file
- This assumes that transactions added to FILE always have same or
- increasing dates, and that transactions on the same day do not get
+ This assumes that transactions added to FILE always have same or
+ increasing dates, and that transactions on the same day do not get
reordered. See also the import command.
- This command also supports output destination and output format selec-
+ This command also supports output destination and output format selec-
tion. Here's an example of print's CSV output:
$ hledger print -Ocsv
@@ -1781,20 +1800,20 @@ COMMANDS
"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
+ 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
+ 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"
+ 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
+ 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.)
print-unique
@@ -1807,7 +1826,7 @@ COMMANDS
show running total from report start date (default)
-H --historical
- show historical running total/balance (includes postings before
+ show historical running total/balance (includes postings before
report start date)
-A --average
@@ -1818,18 +1837,18 @@ COMMANDS
show postings' siblings instead
-w N --width=N
- set output width (default: terminal width or COLUMNS. -wN,M
+ set output width (default: terminal width or COLUMNS. -wN,M
sets description width as well)
-O FMT --output-format=FMT
select the output format. Supported formats: txt, csv.
-o FILE --output-file=FILE
- write output to FILE. A file extension matching one of the
+ write output to FILE. A file extension matching one of the
above formats selects that format.
The register command displays postings, one per line, and their running
- total. This is typically used with a query selecting a particular
+ total. This is typically used with a query selecting a particular
account, to see that account's activity:
$ hledger register checking
@@ -1838,8 +1857,8 @@ COMMANDS
2008/06/02 save assets:bank:checking $-1 $1
2008/12/31 pay off assets:bank:checking $-1 0
- The --historical/-H flag adds the balance from any undisplayed prior
- postings to the running total. This is useful when you want to see
+ 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
@@ -1849,23 +1868,23 @@ COMMANDS
The --depth option limits the amount of sub-account detail displayed.
- The --average/-A flag shows the running average posting amount instead
+ 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
+ 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 --related/-r flag shows the other postings in the transactions of
the postings which would normally be shown.
- With a reporting interval, register shows summary postings, one per
+ 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
+ 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
@@ -1882,7 +1901,7 @@ COMMANDS
2008/11 0 $-2
2008/12 0 $-2
- Often, you'll want to see just one line per interval. The --depth
+ Often, you'll want to see just one line per interval. The --depth
option helps with this, causing subaccounts to be aggregated:
$ hledger register --monthly assets --depth 1h
@@ -1890,18 +1909,18 @@ COMMANDS
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
+ 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.
Custom register output
- register uses the full terminal width by default, except on windows.
- You can override this by setting the COLUMNS environment variable (not
+ register uses the full terminal width by default, except on windows.
+ You can override this by setting the COLUMNS environment variable (not
a bash shell variable) or by using the --width/-w option.
- The description and account columns normally share the space equally
- (about half of (width - 40) each). You can adjust this by adding a
+ 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:
@@ -1918,12 +1937,12 @@ COMMANDS
$ hledger reg -w 100,40 # set overall width 100, description width 40
$ hledger reg -w $COLUMNS,40 # use terminal width, and set description width
- This command also supports output destination and output format selec-
+ This command also supports output destination and output format selec-
tion.
register-match
Print the one posting whose transaction description is closest to DESC,
- in the style of the register command. Helps ledger-autosync detect
+ in the style of the register command. Helps ledger-autosync detect
already-seen transactions when importing.
rewrite
@@ -1933,7 +1952,7 @@ COMMANDS
Show some journal statistics.
-o FILE --output-file=FILE
- write output to FILE. A file extension matching one of the
+ write output to FILE. A file extension matching one of the
above formats selects that format.
$ hledger stats
@@ -1948,16 +1967,16 @@ COMMANDS
Accounts : 8 (depth 3)
Commodities : 1 ($)
- The stats command displays summary information for the whole journal,
- or a matched part of it. With a reporting interval, it shows a report
+ The stats command displays summary information for the whole journal,
+ or a matched part of it. With a reporting interval, it shows a report
for each report period.
- This command also supports output destination and output format selec-
+ This command also supports output destination and output format selec-
tion.
tags
- List all the tag names used in the journal. With a TAGREGEX argument,
- only tag names matching the regular expression (case insensitive) are
+ List all the tag names used in the journal. With a TAGREGEX argument,
+ only tag names matching the regular expression (case insensitive) are
shown. With additional QUERY arguments, only transactions matching the
query are considered.
@@ -1967,34 +1986,34 @@ COMMANDS
$ hledger test
Cases: 74 Tried: 74 Errors: 0 Failures: 0
- This command runs hledger's built-in unit tests and displays a quick
+ This command runs hledger's built-in unit tests and displays a quick
report. With a regular expression argument, it selects only tests with
matching names. It's mainly used in development, but it's also nice to
be able to check your hledger executable for smoke at any time.
ADD-ON COMMANDS
- hledger also searches for external add-on commands, and will include
+ hledger also searches for external add-on commands, and will include
these in the commands list. These are programs or scripts in your PATH
- whose name starts with hledger- and ends with a recognised file exten-
+ whose name starts with hledger- and ends with a recognised file exten-
sion (currently: no extension, bat,com,exe, hs,lhs,pl,py,rb,rkt,sh).
- Add-ons can be invoked like any hledger command, but there are a few
+ Add-ons can be invoked like any hledger command, but there are a few
things to be aware of. Eg if the hledger-web add-on is installed,
o hledger -h web shows hledger's help, while hledger web -h shows
hledger-web's help.
- o Flags specific to the add-on must have a preceding -- to hide them
- from hledger. So hledger web --serve --port 9000 will be rejected;
+ o Flags specific to the add-on must have a preceding -- to hide them
+ from hledger. So hledger web --serve --port 9000 will be rejected;
you must use hledger web -- --serve --port 9000.
- o You can always run add-ons directly if preferred:
+ o You can always run add-ons directly if preferred:
hledger-web --serve --port 9000.
- Add-ons are a relatively easy way to add local features or experiment
- with new ideas. They can be written in any language, but haskell
- scripts have a big advantage: they can use the same hledger (and
- haskell) library functions that built-in commands do, for command-line
+ Add-ons are a relatively easy way to add local features or experiment
+ with new ideas. They can be written in any language, but haskell
+ scripts have a big advantage: they can use the same hledger (and
+ haskell) library functions that built-in commands do, for command-line
options, journal parsing, reporting, etc.
Here are some hledger add-ons available:
@@ -2012,7 +2031,7 @@ ADD-ON COMMANDS
hledger-web provides a simple web interface.
Third party add-ons
- These are maintained separately, and usually updated shortly after a
+ These are maintained separately, and usually updated shortly after a
hledger release.
diff
@@ -2020,7 +2039,7 @@ ADD-ON COMMANDS
journal file and another.
iadd
- hledger-iadd is a curses-style, more interactive replacement for the
+ hledger-iadd is a curses-style, more interactive replacement for the
add command.
interest
@@ -2028,19 +2047,19 @@ ADD-ON COMMANDS
ing to various schemes.
irr
- hledger-irr calculates the internal rate of return of an investment
+ hledger-irr calculates the internal rate of return of an investment
account.
Experimental add-ons
- These are available in source form in the hledger repo's bin/ direc-
+ These are available in source form in the hledger repo's bin/ direc-
tory; installing them is pretty easy. They may be less mature and doc-
- umented than built-in commands. Reading and tweaking these is a good
+ umented than built-in commands. Reading and tweaking these is a good
way to start making your own!
autosync
hledger-autosync is a symbolic link for easily running ledger-autosync,
- if installed. ledger-autosync does deduplicating conversion of OFX
- data and some CSV formats, and can also download the data if your bank
+ if installed. ledger-autosync does deduplicating conversion of OFX
+ data and some CSV formats, and can also download the data if your bank
offers OFX Direct Connect.
chart
@@ -2050,21 +2069,21 @@ ADD-ON COMMANDS
hledger-check.hs checks more powerful account balance assertions.
ENVIRONMENT
- COLUMNS The screen width used by the register command. Default: the
+ COLUMNS The screen width used by the register command. Default: the
full terminal width.
LEDGER_FILE The journal file path when not specified with -f. Default:
- ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
+ ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
nal).
FILES
- Reads data from one or more files in hledger journal, timeclock, time-
- dot, or CSV format specified with -f, or $LEDGER_FILE, or
- $HOME/.hledger.journal (on windows, perhaps
+ Reads data from one or more files in hledger journal, timeclock, time-
+ dot, or CSV format specified with -f, or $LEDGER_FILE, or
+ $HOME/.hledger.journal (on windows, perhaps
C:/Users/USER/.hledger.journal).
BUGS
- The need to precede addon command options with -- when invoked from
+ The need to precede addon command options with -- when invoked from
hledger is awkward.
When input data contains non-ascii characters, a suitable system locale
@@ -2077,33 +2096,33 @@ BUGS
In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger
add.
- Not all of Ledger's journal file syntax is supported. See file format
+ Not all of Ledger's journal file syntax is supported. See file format
differences.
- On large data files, hledger is slower and uses more memory than
+ On large data files, hledger is slower and uses more memory than
Ledger.
TROUBLESHOOTING
- Here are some issues you might encounter when you run hledger (and
- remember you can also seek help from the IRC channel, mail list or bug
+ Here are some issues you might encounter when you run hledger (and
+ remember you can also seek help from the IRC channel, mail list or bug
tracker):
Successfully installed, but "No command `hledger' found"
stack and cabal install binaries into a special directory, which should
- be added to your PATH environment variable. Eg on unix-like systems,
+ be added to your PATH environment variable. Eg on unix-like systems,
that is ~/.local/bin and ~/.cabal/bin respectively.
I set a custom LEDGER_FILE, but hledger is still using the default file
- LEDGER_FILE should be a real environment variable, not just a shell
- variable. The command env | grep LEDGER_FILE should show it. You may
+ LEDGER_FILE should be a real environment variable, not just a shell
+ variable. The command env | grep LEDGER_FILE should show it. You may
need to use export. Here's an explanation.
- "Illegal byte sequence" or "Invalid or incomplete multibyte or wide
+ "Illegal byte sequence" or "Invalid or incomplete multibyte or wide
character" errors
In order to handle non-ascii letters and symbols (like ), hledger needs
an appropriate locale. This is usually configured system-wide; you can
also configure it temporarily. The locale may need to be one that sup-
- ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always,
+ ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always,
I'm not sure yet).
Here's an example of setting the locale temporarily, on ubuntu
@@ -2122,7 +2141,7 @@ TROUBLESHOOTING
$ echo "export LANG=en_US.UTF-8" >>~/.bash_profile
$ bash --login
- If we preferred to use eg fr_FR.utf8, we might have to install that
+ If we preferred to use eg fr_FR.utf8, we might have to install that
first:
$ apt-get install language-pack-fr
@@ -2143,7 +2162,7 @@ TROUBLESHOOTING
REPORTING BUGS
- Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
+ Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list)
@@ -2157,7 +2176,7 @@ COPYRIGHT
SEE ALSO
- hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
+ hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)
@@ -2165,4 +2184,4 @@ SEE ALSO
-hledger 1.9 March 2018 hledger(1)
+hledger 1.9.1 April 2018 hledger(1)